heimgewebe/repoground

# repoground – 索引 文件夹快速概览： - `scripts/` – 可重用的辅助脚本 - `merger/repoground/` – **RepoGround** – 仓库数据准备、检索和只读 Evidence-Surfaces。 以前的独立 Repomerger 和 OmniWandler 不再属于活跃的 RepoGround 产品界面。它们的历史实现依然可以通过 Git 历史记录追溯；具有约束力的边界决策位于 [`docs/architecture/product-boundaries.md`](docs/architecture/product-boundaries.md)。 ## 入门与文档 - 🚀 [入门指南](docs/GETTING_STARTED.md) – 生成 dump、读取 bundle、进行搜索 - 📖 [术语表](docs/glossary.md) · [常见问题解答](docs/FAQ.md) - 🗺️ [系统地图](docs/architecture/system-map.repoground.md) – 模块间协作 - 🧭 [Master-Roadmap](docs/roadmap/repoground-master-roadmap.md) – 顺序与 Tracks - 🤝 [贡献指南](CONTRIBUTING.md) · [更新日志](CHANGELOG.md) ## 自由、开放与社区驱动 RepoGround 是基于 [Apache License 2.0](LICENSE) 的自由开源软件。它可以被免费使用、研究、修改和 重新分发，无需支付任何使用费。项目名称仅作为防御性的身份边界受到保护；广泛的社区使用、兼容性使用以及明确标识的分支使用在 [TRADEMARK_POLICY.md](TRADEMARK_POLICY.md) 中进行了说明。 ## 用法示例 ### RepoGround（推荐） 为 LLM 准备仓库的主要工具。 `merger.repoground.frontends.pythonista.build` 是用于本地模块调用的直接 RepoGround dump/bundle 生成器，特别是针对 Pythonista/iPad 环境。 `merger.repoground.cli.serve` 是 RepoGround 的服务/宿主接口，而不是直接的 `RepoGround . --level ...` 调用；RepoGround 依然作为运行在 Home PC/服务层的核心组件。 ``` # 概述 python3 -m merger.repoground.frontends.pythonista.build . --level overview # Full Merge mit Split (20MB), voller Metadichte und Dual-Output python3 -m merger.repoground.frontends.pythonista.build . \ --level max \ --split-size 20MB \ --meta-density full \ --output-mode dual ``` 如果在本地环境中模块调用无效，也可以直接执行文件： ``` python3 merger/repoground/frontends/pythonista/build.py . --level max --split-size 20MB --meta-density full --output-mode dual ``` 详情请参阅 [merger/repoground/repoground-build-spec.md](merger/repoground/repoground-build-spec.md)。 ### Agent Reading Pack（LLM Agent 入门） 每个 bundle 都包含 `.agent_reading_pack.md` —— 这是一个紧凑且确定的 Markdown 文档，LLM Agent 应该**首先**阅读它。它是 用于**导航，而非事实来源**（`authority=navigation_index`，`canonicality=derived`）； 唯一的事实来源依然是 `canonical_md`。 该 Pack 总结了： - **Reading Policy** + Artifact 角色（哪个 artifact 可以陈述什么）， - **HOW_TO_SEARCH**：用于全文搜索、Range 解析和 Citations 的具体 CLI 命令， - **OUTPUT_HEALTH_SUMMARY**：bundle 的自测判定结果， - **TOP_CHUNK_SPANS**：根据 Chunk-Coverage 统计出的每个源文件中最大的聚合 canonical spans （用于在 `canonical_md` 中进行精确引用的导航辅助） —— **并非** 重要性声明。（以前称为：`TOP_FILES`。） - **EPISTEMIC_EMPTINESS**：bundle 中缺失的内容。 独立生成或重新生成： ``` python3 -m merger.repoground.cli.main agent-pack produce .bundle.manifest.json --json ``` ### RepoGround 作为本地 MCP 服务器 现有的 Brief bundle 可以直接作为用于 Coding Agent 的 MCP 资源和工具挂载。对于 MCP Client，提供了独立于 checkout 的启动器： ``` python3 /absoluter/pfad/zu/repoground/scripts/repoground-mcp-stdio.py \ --bundle-root /absoluter/pfad/zu/briefs \ --repo-root /absoluter/pfad/zum/repository ``` 服务器默认提供 `ask_context`、`grounding_verify`、`live_freshness` 以及 `repoground://snapshot/...` 资源。读取访问不会创建或更新 snapshot。Live-Freshness 会将不同的 `HEAD` 或 Dirty Working Tree 报告为 `stale`。 只要服务器没有明确使用 `--enable-snapshot-create` 启动，写入式的 `snapshot_create` 路径就会保持隐藏。在此模式下，源仓库和输出目标 依然绑定在服务器启动时的 `--repo-root` 和 `--bundle-root` 参数上。 配置、状态和安全边界： [RepoGround MCP stdio](docs/usage/repoground-mcp-stdio.md)。 ### Atlas – 可选的 Observation 子系统 Atlas 是 RepoGround 中一个可选的文件系统观察接口。 它**不是** canonical 仓库发布和检索 pipeline 的一部分： 普通的 RepoGround dump、查询或 bundle 发布都不会启动 Atlas 扫描。Atlas 只能通过显式的 `repoground atlas` CLI 或经过身份验证的 `/api/atlas` endpoint 激活。 Atlas 可以扫描文件系统根目录并生成有边界的 observation artifact，同时依然与仓库检查 pipeline 保持独立。 伪文件系统和易失性路径（`/proc`、`/sys`、`/dev`、`/run` 等）默认被排除，以避免递归循环、设备流和无意义的 inventory 条目。该功能完全不会改变 merge pipeline。 **Atlas Root 模型：** Atlas 在内部采用形式化的 root 模型，允许针对不同类型的目标执行，而无需隐式回退或隐藏行为。API 请求中的 `root_kind` 必须是以下之一： * `preset`：用于指代预定义的、受信任的目录，如 `hub`、`merges` 或 `system`（服务用户的 home 目录）。`system` 预设需要回环地址、配置的 Bearer 身份验证，以及在启动期间成功解析的 Home 路径。如果 Home 不可用，服务将以经过身份验证的仅 root 模式启动，从 `/api/fs/roots` 中省略 `system`，并保留对显式文件系统根目录的访问权限。 * `token`：与不透明的、服务器签名的 token 一起使用，主要用于文件选择器和外部集成。 * `abs_path`：显式指向绝对的文件系统路径（例如 `/home/user/project`）。这是一种显式的内部模式。严格拒绝遍历漏洞攻击（`..`）或相对路径。请注意，WebUI 会在创建 API 请求之前捕获无效的手动路径输入（例如输入了 "home" 而不是 "/home"），从而防止不必要的 Bad Requests。 用法示例： ``` # Service API: broad system roots require loopback plus --token / RLENS_TOKEN. # 独立的 Atlas CLI 仍然是本地的、显式的文件系统操作。 repoground atlas scan / repoground atlas scan /home repoground atlas scan /etc ``` ### JSONL 工具 用于调用可用工具的最小化命令： ``` bash scripts/jsonl-validate.sh --help bash scripts/jsonl-tail.sh --help ``` - `scripts/jsonl-validate.sh` – 根据 JSON Schema (AJV v5) 验证 NDJSON（每行一个 JSON 实体）。 - `scripts/jsonl-tail.sh` - `scripts/jsonl-compact.sh` ## Organismus 上下文 本仓库是 **Heimgewebe-Organismus** 的一部分。 本仓库在 Organismus 中的角色：**Merger**、**Scanner** 以及用于结构化仓库准备的核心认知层。 整体的架构、轴线、角色和 Contracts 集中描述于 👉 [`metarepo/docs/heimgewebe-organismus.md`](https://github.com/heimgewebe/metarepo/blob/main/docs/heimgewebe-organismus.md) 👉 [`metarepo/docs/heimgewebe-zielbild.md`](https://github.com/heimgewebe/metarepo/blob/main/docs/heimgewebe-zielbild.md)。 本仓库的所有角色定义、数据流和 Contract 分配 均锚定于此。 ### Merge Job 去重 当通过 WebUI 请求 non plan 的仓库 Merge 时，JSON Payload 会包含 `force_new: true`。这确保了会执行一次全新的 merge，而不是重用缓存的 Job。Plan-only Jobs 会省略 `force_new` 标志，以便在可能的情况下重用缓存的计划结果。

标签：LLM预处理, Python, SOC Prime, 代码上下文, 代码索引, 开发工具, 文档结构分析, 无后门, 时序数据库, 检索增强生成(RAG), 逆向工具, 防御加固