使用说明

一、init 做了什么

在业务仓库根执行：

flow2spec init [cursor|claude|codex|dsh ...]
# 使用英文模板：
flow2spec init [cursor|claude|codex|dsh ...] --locale en-US
# 需要强制重置 .Knowledge 到模板时：
flow2spec init [cursor|claude|codex|dsh ...] --reset-knowledge

init 与「知识库升级」是两件事：init 只做结构补齐，业务语义（topics 内容、路由词条、stock-docs/req-docs）由 f2s-kb-add、f2s-kb-fix、f2s-kb-feat、f2s-kb-sync、f2s-kb-build 等技能维护。跨版本升级用 f2s-kb-upgrade，不要把单独 init 当作升级命令。

模板语言

flow2spec init 默认使用 zh-CN 模板；可通过 --locale en-US 使用英文模板。locale 只决定 Flow2Spec 包模板（rules / skills / knowledge template / hooks / AGENTS）的自然语言，不翻译已有业务知识库内容。f2s-kb-upgrade 默认沿用项目 flow2spec.config.json.locale，字段不存在时按 zh-CN 补齐。

f2s-* 与 flow2spec.config.json：多端多重提示（权威仍为磁盘 JSON）

执行任意 f2s-* 技能前，需要让 Agent 拿到 subAgent / switchAgentVerification / changeTracking 等实际值。Flow2Spec 在 不同客户端 用 不同机制 强化这一点；它们彼此补充，不互相替代，权威始终是项目根 flow2spec.config.json（须用 Read 与磁盘一致后再进技能正文）。

字段语义与默认值规则见 命令说明 § 6) 子 Agent 配置说明。设计视角见 设计说明 § 四、5.1；口述见 Flow2Spec 演讲稿 Slide 13b。

二、目录约定

核心区分：stock-docs/ 放沉淀文档（驱动知识路由），req-docs/ 放技术方案（驱动编码实现），两者不互换。

完整目录说明见 目录与路径约定。

三、典型工作场景

变更追踪与跨会话续作（推荐）

在 flow2spec.config.json 按技能开启 changeTracking（各子项独立）：

{
  "changeTracking": {
    "feat": true,
    "fix": true,
    "implement": true
  }
}

开启后，f2s-kb-feat / f2s-kb-fix / f2s-implement-tech-design 执行时会在 .task/active/ 自动创建任务清单，逐步勾选，完成后归档。下次会话描述相关内容时，f2s-task 规则会匹配并加载剩余步骤，无需重复交代上下文。

若你关闭了 changeTracking 但仍临时需要 .task/ 清单，可显式调用 f2s-req-plan（不读配置、始终建清单）——这是兜底用法，非常规主路径；详见 命令说明 § f2s-req-plan。

新需求开发

f2s-req-clarify 一句话需求或文档 → f2s-req-tech → 实现xx技术方案 （会严格按照implement-tech-design规则走）
实现完成后需新增能力→ f2s-kb-feat
实现完成后需修bug→ f2s-kb-fix
调试完成后-> f2s-kb-sync
最后->f2s-git-commit

需求已明确时可跳过 f2s-req-clarify，直接从 f2s-req-tech 开始。技术方案落入 req-docs/ 后，由 implement-tech-design 规则驱动编码。

文档沉淀

新增架构文档沉淀：f2s-doc-arch → f2s-doc-final → f2s-kb-build
PDF/初稿沉淀：     f2s-doc-final → f2s-kb-build

把架构说明或 PDF 终稿纳入知识路由（生成 topics/matchers/manifest-routing）。若仅有 PDF 且要入库，先用 f2s-doc-final 转为终稿再 f2s-kb-build；f2s-doc-pdf 仅把 PDF 转为 req-docs/ 下的 Markdown 便于编辑，不作为「PDF 直驱编码」的推荐路径。

存量能力补录

f2s-kb-add      # 多文件聚合，从源码/文档提取
f2s-kb-sync      # 从当前会话推断已实现能力

代码已落地但知识库没有记录时使用。f2s-kb-add 适合批量导入，f2s-kb-sync 适合会话结束时的即时沉淀。

日常维护

f2s-kb-fix       # 修复实现或规则错误，自动同步知识库
f2s-kb-feat      # 新增能力，自动同步知识库
f2s-kb-sync      # 定期同步或补录
f2s-kb-merge     # Git 合并后解决上下文冲突

知识库跨版本升级

Core-only 更新（Template Version 不变）：更新 Core 后幂等 init 刷新 Hook，不进入 f2s-kb-upgrade
Template 更新：init 后按 projectRev == pkgRev 走快速路径，不等时进入 f2s-kb-upgrade 完整流程
旧版布局（流程 V1）：不再内置迁移；用历史版本包（@3.4.x 及更早）一次性迁移或手动迁入 .Knowledge

flow2spec version 展示 CLI、Core、Core Range、Template、Protocol；flow2spec update --check 检查更新，flow2spec update --cli 更新 latest CLI 及其兼容 Core，flow2spec update --core 保持当前 CLI 版本并刷新其兼容范围内的 Core。Core 兼容更新可独立发布；已安装依赖不会静默更新，项目锁文件仍固定本地解析结果。SessionStart Hook 同时检查 Core 与 Template：Core-only 更新不触发知识库升级；Template 更新才在 init 后按 projectRev / pkgRev 决定是否执行 f2s-kb-upgrade。更新检查失败会静默跳过，不影响当前命令；CI 或设置 FLOW2SPEC_SKIP_UPDATE_CHECK=1 时 CLI 自检不打扰当前流程。

Codex 项目执行 flow2spec init codex 后会写入 .codex/hooks.json、.codex/hooks/f2s-config-session.js 与 .codex/hooks/f2s-update-check.js：前者在 Codex SessionStart 的 startup|resume 事件注入一次配置摘要，后者自动检查知识库版本；首次生成或 hook 内容变化后，需要在 Codex 中通过 /hooks 信任该项目 hook。flow2spec.config.json 中 updateCheck.enabled=false 时仅跳过版本检查，不影响配置摘要注入。

DeepSeek Harness 优先安装原生 Cordis 插件 @double-coding/flow2spec-deepseek-harness（独立仓 Flow2Spec-DeepSeek-Harness）。未装插件时执行 flow2spec init dsh：Flow2Spec 会把项目级技能写入 .dsh/skills/，把规则长文镜像到 .dsh/topics/，并生成 .dsh/AGENTS.md 目录指针。若仓库根没有 AGENTS.md，init 会生成一份适配 Harness 的完整入口；若已有该文件则保留用户内容，不覆盖。

Cursor 项目执行 flow2spec init cursor 后会写入 .cursor/hooks.json 与 .cursor/hooks/f2s-update-check.js，在 Cursor sessionStart 自动检查知识库版本；脚本通过 additional_context 把升级提示注入会话。flow2spec.config.json 中 updateCheck.enabled=false 时跳过检查。

Claude 项目执行 flow2spec init claude 后会写入 .claude/settings.json、.claude/hooks/f2s-config-session.js、.claude/hooks/f2s-config-inject.js 与 .claude/hooks/f2s-update-check.js：SessionStart 注入配置摘要并分别检查 Core/Template，PreToolUse Skill 仅在调用 f2s-* Skill 前做守门提示。Hook 通过 additional_context 注入对应的 Core-only 或 Template 更新动作；当天缓存仍标记需更新时，新会话会继续提醒，完成更新后清理 .Knowledge/update-check.json。

多人协作

Flow2Spec 把协作拆成两条互不干扰的线：.Knowledge/ 走 Git，全员共享；.task/ 只在本地，按 developerId 分层。团队沉淀和个人过程分开管，不用为一份 todo.json 反复解冲突。

任务进度：本地按人隔离

最小配置：

{
  "collaboration": {
    "enabled": true,
    "developerId": ""
  }
}

developerId 留空时按 git identity 兜底解析；非 ASCII 的 git identity 会退化到 dev-<sha256 前 8 位> 的稳定 hash id，同时在解析上下文里挂 warnings 提醒改成显式英文 id——不会静默降到 legacy，也不会因为字符集炸掉。解析优先级、hash 兜底与迁移步骤详见 目录与路径约定 § .task/ 的两种形态。

执行约束是硬的：rules/f2s-task 只准读写当前 developer 的 TASK_ROOT，禁止扫别人 .task/<otherId>/ 目录，也不会自动跨人合并 todo.json。

知识库：delta + 乐观锁

.Knowledge/topics/*.md 的 frontmatter 有一个 revision 计数。技能不再直接改 topic 文件，而是往当前任务目录写一份 kb-delta.json（路径 .task/<id>/active/<task-name>/kb-delta.json），带上 baseRevisions 与 changes[]；真正落盘由 flow2spec kb 子命令统一处理：

flow2spec kb status   # 扫本人 active 任务的 delta、routing 漂移、topic 校验
flow2spec kb check    # 严格校验 manifest/topic/frontmatter/revision
flow2spec kb plan <delta.json>    # 预演能否自动合入，不落盘
flow2spec kb apply <delta.json>   # 真正合入 .Knowledge/
flow2spec kb build    # 由 topic frontmatter 归一化 routing 元数据

变更类型白名单：appendBody / replaceBody / updateFrontmatter / createTopic。空 body 的 append/replace 在 parse 阶段就被拒，不会漏到 apply；baseRevisions 不匹配盘上真值时 plan 直接报冲突，git pull 拉最新 topic 后重写 delta 里对应 change 即可。命令细节见 命令说明 § 7) flow2spec kb CLI，机制原理见 体系与原理 § 6. 多人协作的两条隔离线。

日常节奏

正常走 f2s-git-commit 时，Agent 会自动完成 check → status → plan → apply → build → check，不要求开发者手动逐条执行。需要独立排查或接入 CI 时，对应的 shell 流程是：

git pull                # 拉队友的 .Knowledge/
flow2spec kb status     # 看有没有 routing 漂移或本地待落盘 delta
… 走 f2s-kb-feat / f2s-kb-fix / f2s-implement-tech-design …
flow2spec kb plan  .task/<id>/active/<task>/kb-delta.json   # dry-run
flow2spec kb apply .task/<id>/active/<task>/kb-delta.json   # 落盘
git add .Knowledge/ && git commit && git push

.task/ 全程留在本地，不进 push；.Knowledge/ 每次 apply 之后再提交。只要两个人基于同一个 revision 修改同一 topic，先合入的一方就会推进版本，另一方在拉取后重新 plan 时会被阻塞，即使双方碰的是不同段落。锁是 topic 级，不是行级。

完整协作模型、同 topic 冲突示例与管理者视角见 团队协作。

四、Agent 执行配置

通过项目根 flow2spec.config.json 控制，字段完整规则见 命令说明 § 6) 子 Agent 配置说明。各端如何被提示读到配置、为何仍以 Read 为权威见 § 一（本 § 仅说明何时打开各开关）。

何时开启 subAgent: true：任务规模较大时（多模块并行实现、批量文档入库、大规模迁移）。开启后各技能按自身规模门槛决定是否实际拆分，未达门槛的仍在主 agent 内完成。

何时开启 switchAgentVerification: true：需要更高落盘一致性时（大规模迁移、重要方案实现）。代价是增加执行轮次；常规维护场景默认 false 足够。须搭配 subAgent: true 才能触发”主落子验”方向的交叉。

何时开启 changeTracking.*：希望每次技能执行自动留下可续作的任务清单时。各技能子项独立配置，互不影响：

{
  "changeTracking": {
    "feat": true,
    "fix": false,
    "implement": true
  }
}

changeTracking 全关且仍要任务清单时，再考虑 f2s-req-plan（见 § 三「变更追踪」脚注）。

五、规则改造建议

• 项目特化「按技术方案实现」逻辑时，优先调整 f2s-implement-tech-design：Cursor .cursor/rules/f2s-implement-tech-design.mdc，Claude .claude/rules/f2s-implement-tech-design.md；Codex 以 .codex/AGENTS.md 与相关 skills/ 为准
• 再次 init 默认仅补齐缺失模板并做包级结构对齐，不替代 f2s-* 对业务内容的维护；需用模板重置 .Knowledge 时加 --reset-knowledge

六、技能标识

技能以 name 与 description 匹配触发，文件位于 配置根/skills/*/SKILL.md。

七、相关文档

• Flow2Spec 基础介绍
• 命令说明
• 目录与路径约定
• 体系与原理
• 使用案例-模拟对话
• 项目里程碑