repomind-init

RepoMind 初始化知识库

当 .repomind/modules/ 下还没有有效模块文档，或现有知识库明显为空时执行本流程。

核心原则

1. graphify 图谱必须全量重建，不能偷用旧结果。
2. 知识库写入必须合并，不能覆盖已有人工沉淀。
3. RepoMind 不再维护集中式 index.json 或目录 README 作为路由入口。
4. 路由依赖每个知识文件自己的 frontmatter 元数据；其中 description 是首要索引摘要，modules 还要维护关键词。

---
name: "..."
description: "..."
---

元数据约束

所有 concepts/*.md、modules/*.md、troubles/*.md 都必须满足：

• name：当前文件的规范名称，供大模型做首轮匹配。
• description：只写 1-2 句话，专门用于“是否该打开这份文档”的判断；这是首要索引摘要，优先级高于正文润色。

concepts 的 description 必须包含：

• 这个概念是什么。
• 它会在哪些业务场景/产品语境中被提及。
• 它和哪个相邻概念最容易混淆，或核心边界是什么。
• 不要写代码路径、函数名、SQL、字段名。

modules 的 description 必须包含：

• 模块承担的业务职责。
• 什么时候应该打开这份文档。
• 典型影响面或跨模块风险是什么。
• 不要把整份文件清单塞进描述。

modules 还必须维护 keywords：

• 放 3-8 个真正能帮助路由的判别词。
• 优先放：模块名、英文名、核心业务词、核心入口词、常见别称。
• 不要放泛词，例如“系统”“功能”“业务”“模块”。
• 如果模块改动后，用户可能用新的叫法来找它，必须补到 keywords。

troubles 的 description 必须包含：

• 典型现象或触发条件。
• 首查方向、常见根因范围或受影响面。
• 让模型一眼判断“这是不是我要排查的问题”。

步骤 0：先修正旧格式

在读取或写入任何知识文件前，先执行：

repomind kb-migrate

这一步必须每次执行。它会：

• 给旧文档补齐 frontmatter 的 name / description
• 把历史 index.json 中还能复用的信息迁入模块文档
• 删除过时的集中式索引文件和目录 README
• 为未来的格式演进保留长期迁移入口

从这一步开始，只允许按新格式继续工作，不要再回写旧结构。

步骤 1：全量重建图谱

调用 graphify skill 做全量分析，不是增量更新：

• Claude Code：/graphify .
• Codex：$graphify .

完成后继续，不要停在图谱阶段。

步骤 2：确保关键文件可提交

确认以下文件会被 git 跟踪：

• graphify-out/graph.json
• graphify-out/GRAPH_REPORT.md
• graphify-out/manifest.json
• graphify-out/graph.html
• graphify-out/.vocab.txt
• .repomind/concepts/**
• .repomind/modules/**
• .repomind/troubles/**
• .repomind/.kb-format.json

如果需要，执行：

git add graphify-out/ .repomind/

步骤 3：运行 graph-scan

repomind graph-scan

它会生成 .repomind/graph/summary.json，用于辅助判断：

• module_candidates
• entry_files
• communities
• symbols

步骤 4：先读元数据，再决定打开哪些文档

先读取知识库元数据，而不是盲扫全文：

repomind kb-metadata

如果当前知识库为空，继续创建；如果已有文档，先看元数据决定哪些旧文档需要合并。

步骤 5：归纳业务模块和业务概念

基于目录结构、graph summary、入口文件和命名语义，先做高置信筛选。

候选模块分三类：

候选概念分三类：

初始化只生成高置信知识，不要为了凑数量造概念。

步骤 6：创建或合并知识文档

6a：concepts

对每个高置信概念：

1. 如果已存在对应文档，先读取原文并合并。
2. 如果不存在，新建为：

---
name: "Pro 角色"
description: "高级用户身份概念。用于判断权益范围、典型触发场景，以及和 VIP 的区别。"
---

# 概念：Pro 角色

## 是什么

（一句话定义这个概念本身。回答“它到底是什么业务对象/能力/身份”，不要写实现）

## 为什么有

（说明业务目的、历史背景或产品诉求。回答“为什么系统里需要它”，没有证据就写“待确认”）

## 用户侧表现

（描述用户在什么页面、流程、操作里会感知到它；回答“用户看到什么/能做什么/受什么影响”）

## 系统侧数据流

（描述这个概念相关数据从哪里来，经过什么处理，最后在哪里被消费；写数据来源、加工链路、最终表达）

## 核心规则

（写稳定业务规则、边界条件、负向规则。适合按小主题分组，不要抄 if/else）

## 易混淆概念

（写“它不是什么”“和谁容易混”“区别是什么”，帮助后续问答时避免混淆）

写 concept 时：

• 优先写业务定义、用户感知、数据流、边界。
• 不要把实现细节抄成业务卡片。
• description 必须能帮助后续“概念型问题”命中这张卡。

6b：modules

只对业务模块创建或合并模块文档。模板：

---
name: "支付模块"
description: "支付与退款相关模块。用于定位下单、回调、补偿入口和改动影响面。"
keywords:
- "支付"
- "payment"
- "退款"
- "refund"
- "回调"
---

# 支付模块

## 业务描述

（1-3 句话说明这个模块承担的业务职责，回答“这个模块在业务上管什么”）

## 关键代码

（列真正值得作为入口的文件/函数。写“从哪里进、为什么看这里”，不是罗列整个目录）

## 常见修改场景

（列未来最常见的改动入口，例如“改退款规则先看哪里”。回答“遇到某类需求先从哪里下手”）

## AI 注意事项

（写隐性约束、跨模块联动、业务坑点、容易误改的地方。回答“改这里最容易踩什么坑”）

合并规则：

• 业务描述：保留旧描述，只补充新的高置信业务职责。
• 关键代码：按文件路径去重；大文件再细到函数名。
• 常见修改场景：合并去重。
• AI 注意事项：优先保留旧的坑点和边界，再补充新的。
• description：如果模块职责、典型入口或影响面已经变化，必须同步改 frontmatter。
• keywords：如果模块新增别称、入口词、核心业务词或常见搜索词，必须同步更新。

6c：troubles

初始化阶段只保证目录存在，不从代码自动生成排查记录。

• 不创建 README.md
• 不伪造 trouble 文档
• 只在真实排查后由 repomind-summary 维护
• trouble 文档结构和每个小节含义，遵循 repomind-summary 中的排查模板说明

步骤 7：再次校验元数据并提交

写完文档后再次执行：

repomind kb-metadata
git add .repomind/ graphify-out/

目的：

• 确认每个新文档都暴露了 name / description
• 确认没有回写旧的 index.json / README

步骤 8：输出摘要并衔接 PRD

输出初始化摘要时必须包含：

• 新建/合并了哪些 concepts
• 新建/合并了哪些 modules
• 待确认概念
• 待确认模块
• troubles 仍为空是预期行为

然后执行以下交互规则：

• 如果用户在最初请求里已经给了 PRD/需求文档路径，初始化完成后直接调用 repomind-prd，不要再问。
• 如果用户没有给路径，主动询问：

如果你还有历史 PRD/需求文档，我可以继续补业务知识。把文档路径发给我即可；如果现在不需要，回复不用。

• 如果用户回复了路径，立即执行 repomind-prd，不要重新跑 init。