init — 将项目接入全局地图与知识库
init 是让 jj-flow 认识你的本地仓库的入口:它会扫描当前仓库(或你指定的项目族目录),生成一份包含中文名称、别名、所属项目族及待导入知识条数的预览提案;只有在你明确确认后,才会写入本机 ~/.jj-flow/map.md 与 ~/.jj-flow/knowledge/。
| 宿主工具 | 调用写法 |
|---|---|
| Codex | $jj-init … |
| Claude Code / Grok / Qoder | /jj-init … |
一、适用场景与边界
| 场景对比 | 是否使用 init? | 正确入口 |
|---|---|---|
新克隆了一个仓库,想登记到 ~/.jj-flow/map.md,方便后续跨仓按名字调用 | 使用 init | 本页 |
想一次性梳理某个文件夹(如 D:\2025)下的所有直接子仓库并归入同一项目族 | 使用 init | 本页 |
想把当前仓库以前积攒的 ralph 可复用结论批量导入全局知识库 | 使用 init | 本页 |
| 想在当前仓库开始写代码、做业务需求 | 不要用 init | 去 ralph · 单仓任务闭环 |
| 想把项目A 的功能迁移到项目B | 不要用 init | 去 same · 跨仓同源迁移 |
不要混淆 $jj-init 与 jj ralph init
对话里的 $jj-init / /jj-init 是登记全局项目地图;而在当前仓库开启一个业务需求的对话入口是 $jj-ralph(无需写 init 字样)。
二、开始前准备
- 打开要登记的仓库:默认在哪个业务仓库打开对话,就只扫描哪个仓库。
- 批量梳理时准备好父目录路径:如果你想一次性登记多个兄弟仓库,只需记住它们的共同父目录(例如
D:\projects\2025),init会扫描该目录下的直接子仓库。 - 想好项目称呼(可选):你可以直接指定项目的中文名(如“项目A”)和项目族名称;如果不指定,Agent 会根据仓库
AGENTS.md标题或package.json名称给出合理建议(绝不会凭空编造中文名)。
三、标准执行流程(4 步完成接入)
| 步骤 | 谁来做 | 具体发生什么 |
|---|---|---|
| 1. 只读扫描与预览 | Agent | 扫描当前仓库(或指定根目录的直接子仓库),检查哪些已在 ~/.jj-flow/map.md 中、哪些待加入,以及有没有尚未导入的 knowledge-contribution.json。这一步绝不修改任何文件。 |
| 2. 展示可读提案 | Agent | 用简洁的中文列表展示提案(项目名、路径、建议的项目族、待导入知识条数),不会把原始 JSON 直接贴给你。 |
| 3. 你确认或微调 | 你 | 回复“确认加入”,或指出调整意见(例如“名字改成项目B,只加入仓库不导入第 2 条知识”)。 |
| 4. 写入地图与知识库 | Agent | 按你批准的范围更新 ~/.jj-flow/map.md 并导入知识条目,最后汇报实际写入结果。 |
四、完整端到端实战示例
示例 1:把当前单个仓库加入全局地图
text
你:
$jj-init 当前仓加入全局地图,中文名称「项目A」,项目族「核心商城」
Agent(第 1 轮 · 只读提案):
【jj-flow 接入提案】
- 待加入地图:项目A (key: mall-pc-web)
路径:/Users/dev/work/mall-pc-web
家族:核心商城
待写入知识:2 条(1. 登录密码过期弹窗规范;2. 订单金额千分位格式化)
请确认是否按上述提案写入 `~/.jj-flow/map.md` 并导入这 2 条知识?
你(第 2 轮 · 确认范围):
加入地图,知识只写入第 1 条
Agent(第 2 轮 · 执行结果):
已完成接入:
- 已加入地图:项目A (/Users/dev/work/mall-pc-web) · 家族=核心商城
- 知识库:已写入 1 条(登录密码过期弹窗规范);未批准的 1 条未处理示例 2:一次性梳理整个项目族目录
当你本机同一个文件夹下放着多个同源仓库时,可以一次性梳理:
text
你:
$jj-init 梳理 D:\2025,家族「中国大集」
Agent:
【jj-flow 接入提案】(扫描根目录 D:\2025 的直接子仓库)
1. [已登记] 大集PC前台 (seo-daji-web) — 家族=中国大集,待写入知识=0
2. [待加入] 中国大集管理后台 (scsk-admin) — 建议家族=中国大集,待写入知识=1
3. [待加入] 大集H5端 (daji-h5) — 建议家族=中国大集,待写入知识=0
请确认是否将 `scsk-admin` 和 `daji-h5` 加入地图并写入待处理知识?五、常用说法速查
text
# 最简写法:扫描当前仓库并给出接入提案
$jj-init
# 指定中文名称与项目族
$jj-init 当前仓加入全局地图,中文名「项目A」,家族「核心商城」
# 批量扫描某个父目录下的所有直接子仓库
$jj-init 梳理 D:\2025,家族「中国大集」
# 仓库已在地图中,只想把本仓已有的 ralph 结论补进全局知识库
$jj-init 把本仓已有 ralph 贡献补进知识库六、做完之后怎么衔接?
| 你接下来想做的事 | 推荐操作 |
|---|---|
| 在当前仓库开始做业务需求 | 直接输入 $jj-ralph 你的需求描述 |
| 把项目A 做好的功能迁往刚登记的项目B、项目C | 在项目A 提交代码后,输入 $jj-same 交接到 项目B 项目C |
| 检查本机已登记的所有项目与知识库状态 | 在终端运行 npx @brewer/jj-flow@latest doctor 或在对话里让 Agent 查看地图 |
单次 ralph 归档后顺手沉淀一条知识 | 直接在 ralph 对话中说“写入知识库”,确认后即写入当前项目知识库 |
七、文件记录在哪里?
text
~/.jj-flow/
├── map.md # 全局项目地图(按项目族分组的 Markdown 表格,未指定家族的项目归入 ## Ungrouped)
└── knowledge/ # 经你确认后写入的跨项目知识条目与检索索引