project-brain

Project Brain

使用 gh 读取项目单独的 Git 知识库。将知识库视为证据：引用仓库路径和检查过的提交，区分文档中记载的事实与推断，并说明仓库未能解答的问题。

强制预检

在 Git 工作树中规划、回答、审查、诊断、编写文档或更改文件之前：

1. 使用 git rev-parse --show-toplevel 确定当前工作树根目录。
2. 检查该根目录下是否存在 .project-brain.json。
3. 如果文件存在，则调用此工作流并查阅知识库，然后再进行实质性推理或操作。此标记是无条件指令；不要等用户提到 Project Brain，也不要自行判断是否可以不查阅。
4. 阅读足够的相关知识库材料，为任务提供依据。至少在 agent-guide.md 存在时阅读该文件，然后发现并阅读与请求相关的资料。
5. 如果无法访问知识库，请说明具体受阻原因。不要在缺少依据的情况下默默继续。

Project Brain 是一个独立仓库，由标记文件指定。不要认为它位于当前项目中，不要将其添加为子目录，也不要将其克隆到当前工作树中。

确定知识库

1. 从当前工作树根目录读取 .project-brain.json。接受以下格式：

   {
     "repository": "owner/project-brain-repo",
     "defaultBranch": "main"
   }
   

2. 必须包含 repository。如果显式调用了此工作流，但没有标记文件或缺少该字段，请询问 Project Brain 仓库地址，不要猜测。如果标记存在但无效，请报告配置错误并停止。

3. 运行 gh auth status。如果未完成身份验证，请要求用户运行 gh auth login，然后停止。

4. 如果存在 defaultBranch，则使用该值；否则使用 gh repo view OWNER/REPO --json defaultBranchRef --jq '.defaultBranchRef.name' 获取默认分支。

5. 使用 gh api repos/OWNER/REPO/commits/BRANCH --jq '.sha' 获取当前提交，并在回答中附上其短 SHA。

切勿打印令牌或身份验证详情。

阅读上下文

对于已知的特定路径，无需克隆即可获取：

gh api --method GET "repos/OWNER/REPO/contents/PATH" -f "ref=BRANCH" -H "Accept: application/vnd.github.raw+json"

对于发现资料或涉及多个文件的问题，请将配置的分支克隆到新建的临时目录中，该目录必须位于当前项目工作树之外：

gh repo clone OWNER/REPO TEMP_DIR -- --depth 1 --branch BRANCH

在克隆目录中进行搜索。若以下文件存在，请按此顺序阅读：

1. agent-guide.md
2. graphify-out/wiki/index.md
3. 索引中链接的相关 wiki 页面
4. 如果 wiki 缺失或内容不足，则阅读 graphify-out/GRAPH_REPORT.md
5. 被引用的源文件，尤其是 context/ 下由人工编写的材料
6. raw/ 下由机器摄取的记录，用于补充细节，包括 raw/code/{owner}/{repo}/… 下的镜像源代码

如果人工编写的决策与生成的摘要存在冲突，应优先采用人工编写的决策和要求。请明确指出冲突和时效性问题。不要将 graphify-out/ 摘要视为比其源文件更可靠的证据。

raw/code/ 镜像是根据源仓库默认分支头部在上次同步时创建的快照。在实际源仓库中工作时，应优先使用其工作树来确认代码情况；使用 raw/code/ 和代码相关的 wiki 文章了解跨仓库及架构背景。

回答与操作

• 每项重要论断都必须引用知识库相对路径，例如 context/decisions/auth.md。
• 内容涉及较多上下文的回答，结尾应附上 Project Brain: OWNER/REPO@SHORT_SHA。
• 区分文档记载的事实、合理推断和缺失信息。
• 默认仅执行只读操作。
• 不要仅仅因为当前代码与知识库不符，就编辑知识库。
• 如果用户明确要求更新知识库，不要推送到默认分支。应克隆仓库、创建分支、仅编辑相关的人工维护文件，并使用 gh pr create 创建拉取请求以供审查。切勿编辑由机器维护的 raw/ 内容。