brownfield

/ouroboros:brownfield

管理现有 Git 仓库和关联工作树的注册表，以及用作访谈上下文的默认仓库。注册表存储在 Ouroboros DB 中：列表、默认项和搜索都会读取它，且不会遍历文件系统。只有 scan 会遍历磁盘。

ooo brownfield                # List registered repos and set defaults (scans only if none are registered)
ooo brownfield scan           # Rescan the scan root and refresh the search index
ooo brownfield defaults       # Show current defaults
ooo brownfield find <topic>   # Rank registered repos by relevance to a topic
ooo brownfield set 6,18,19    # Set defaults by repo numbers
ooo brownfield detect [path]  # Author mechanical.toml via one AI call

加载 MCP 工具（延迟架构防护）

Ouroboros 工具可能会延迟加载，在某一轮加载的架构可能在下一轮卸载。每次调用 ouroboros_* 之前，请立即使用当前运行时的工具发现功能加载该工具："+ouroboros brownfield" 对应 ouroboros_brownfield。如果工具架构未加载，调用会失败并显示 "Invalid tool parameters"。如果工具已可调用，发现操作不会执行任何操作，预期结果为空。如果工具确实不存在，请停止并说明 Ouroboros MCP 服务不可用。列表、扫描、查找、默认项和设置操作只能使用此 MCP 工具，不能使用 CLI 或 Python 脚本。

默认流程（ooo brownfield）

第 1 步：列出注册表

Tool: ouroboros_brownfield
Arguments: { "action": "query" }

如果 meta.total 为 0，说明尚未注册任何内容：请运行下面的扫描并使用其响应。否则不要扫描；添加或移动仓库后，由用户运行 ooo brownfield scan。

Tool: ouroboros_brownfield
Arguments: { "action": "scan" }

扫描边界：

• 遍历从 scan_root 开始（默认：用户的主目录），最多深入两层目录（可找到 ~/repo 和 ~/group/repo，不会找到更深层级的仓库）。
• 不会遍历以点开头的目录和 node_modules 等嘈杂目录。
• 遍历到普通仓库（.git 目录）和关联工作树（.git 文件）时，仅注册其自身。不会扩展 Git 工作树家族，因此不会纳入深度范围之外的工作树（例如 .ouroboros/worktrees 下的工作树）。
• 没有远程仓库或远程仓库名称不是 origin 的仓库也符合条件。会保留现有默认项；不会移除已不在磁盘上的仓库。
• 重新扫描时，会跳过已注册仓库的 git 检查；只有在文件发生变化时，才会重建仓库的搜索文档（清单名称和描述、README 开头内容、顶层条目名称）。

查询或扫描响应中的 text 已包含编号 {id}. {name} 列表，并在默认项旁标有 *（查询行还包含 : {path} - {desc}）；无需再调用 MCP 工具列出仓库。请在代码块中以纯文本双列网格显示编号和名称（不要使用 Markdown 表格），并原样保留 * 标记：

Scan complete. 8 repositories registered.

 1. repo-alpha                   5. repo-epsilon
 2. repo-bravo *                 6. repo-foxtrot
 3. repo-charlie                 7. repo-golf *
 4. repo-delta                   8. repo-hotel

如果扫描未找到任何内容，请说 "No git repositories or worktrees found." 并停止。

第 2 步：选择默认项

不要使用当前运行时的 ask_user 对话框进行此选择：工具调用之间的文本可能不会显示，对话框预览也会截断较长列表。相反，请以仓库网格作为最终消息结束本轮，并通过普通聊天回复收集选择。在网格正下方追加：

• 有默认项时：Current defaults: <names> (numbers <numbers>)，然后说 "Reply with repo numbers to change defaults (e.g. "6, 18, 19"), "keep" to keep the current defaults, or "none" to clear them."
• 没有默认项时：No defaults set.，然后说 "Reply with repo numbers to set defaults (e.g. "6, 18, 19"), or "none" to run interviews in greenfield mode."

网格之后不要进行任何工具调用；面包屑页脚仍应是最后一行。

下一轮解析回复：数字（任意分隔符）→ 对应索引；"keep" → 确认默认项不变，不调用 MCP；"none" → 空索引；其他任何内容 → 用纯文本再次询问，绝不猜测。然后通过一次调用更新所有默认项（此操作会替换所有现有默认项）：

Tool: ouroboros_brownfield
Arguments: { "action": "set_defaults", "indices": "<comma-separated IDs>" }

例如 { "action": "set_defaults", "indices": "6,18,19" }，或者对于 "none"，使用 "indices": ""。

第 3 步：确认

说出新的默认项，并说明它们将用作访谈上下文；对于 "none"，请说明访谈将以 greenfield 模式运行，之后可通过 ooo brownfield 设置默认项。

子命令

• scan：运行 Step 1 扫描调用（即使已注册仓库）；显示表格并停止。

• defaults：运行 Step 1 查询调用（不扫描），仅显示 * 仓库；如果没有，则显示 “未设置默认仓库。运行 'ooo brownfield' 进行配置。”

• find <topic>：按主题对已注册仓库排序，不进行扫描：

  Tool: ouroboros_brownfield
  Arguments: { "action": "query", "text": "<topic>" }
  

  按最佳匹配优先显示返回的行（编号、名称、* 标记、分数；默认显示前 10 个，用户要求更多时则传入 limit），并提供 ooo brownfield set <numbers>。排序基于词法匹配（对名称、描述、路径、清单、README 开头部分和顶层条目执行 BM25），因此匹配的是词语而非含义：如果没有匹配项，请说明这一点，并建议使用其他关键词，或运行 ooo brownfield 查看完整列表。如果响应指出某些仓库没有搜索文档，请说明运行 ooo brownfield scan 可为其建立索引。

• set <indices>：解析逗号分隔的索引，并在不扫描的情况下调用 { "action": "set_defaults", "indices": "<indices>" }；确认默认项已更新。

• detect [path]：针对目标目录（默认为当前工作目录）进行一次 AI 调用，生成带有经过验证的 lint/build/test/static/coverage 命令的 .ouroboros/mechanical.toml；评估的 Stage 1 会原样读取这些命令。若不存在 toml，评估会自动运行此操作，因此仅在需要预先编写文件、构建工具变更后刷新（--force），或在 Stage 1 信任这些命令前审查它们时，才显式运行此子命令。此子命令通过当前运行时的 run_shell 功能使用 CLI：

  uvx --python '>=3.12' --from ouroboros-ai ouroboros detect [path]
  # or, if already installed:
  ouroboros detect [path] [--force]
  

  打印生成的 toml，供用户确认或编辑。如果 detect 报告“无法提出任何可验证的命令”，请说明原因（没有清单、LLM 不可用、所有建议均被丢弃），并建议手动编写最简 toml；添加一条 test = "pytest -q" 之类的条目，即可让 Stage 1 重新执行该检查。

RFC #1392 状态提示页脚

在最终回复末尾，严格以一行 ◆ <current state> → next: <recommended action> 收尾。尽可能通过 ouroboros_session_status 获取实时会话状态来确定状态，否则根据此技能的实际结果确定。绝不使用线性的 Step N of M 页脚；如果下一步确实有多种选择，请列出 2-3 个选项。