跳转至

使用指南

这篇文档假设你从未接触过 shanforge。

目标是让你在第一次使用时，知道：

  • 你到底在用什么
  • 开始前要准备什么
  • 你的项目属于哪一类
  • 第一轮会话应该怎么开始
  • AI 做完后你应该检查什么

1. 先用一句话理解 shanforge

shanforge 不是一个独立的 GUI 软件。

它是一套让 Codex / Gemini CLI 以“软件工厂”方式推进项目的脚本、规则、文档和工作流。

你通常不是自己手敲一堆底层命令，而是：

  1. 用自然语言告诉 AI 当前项目状态和目标
  2. 让 AI 先按项目规则自行读取必要上下文
  3. 让 AI 调用合适的 factory-* 脚本
  4. 让结果回写到代码、正式文档、内部控制面摘要和工作项

2. 使用前要准备什么

2.1 基本环境

开始前至少要满足下面条件：

  • 已安装可用的 Codex 或 Gemini CLI
  • 已安装 uv
  • 本机可提供 Python 3.14+
  • 你能读取和修改 shanforge 仓库
  • 你对目标项目目录有读写权限

2.2 先确认 shanforge 仓库本身是完整的

进入 shanforge 仓库根目录后，确认下面目录存在：

  • scripts/
  • skills/
  • docs/

2.3 可选动作：同步共享 skills

如果你希望把当前仓库里的共享 skills 同步到本地 Codex / Gemini CLI / Agents 技能目录，可以执行：

uv run python scripts/sync-codex-skills

这一步不是必需，但第一次搭环境时通常值得做一次。

补充约定：

  • 当你在支持 slash skill 的宿主里直接输入 /技能名，默认语义应是“立即调用该 skill 的默认工作流”。
  • /技能名 不应该只触发“读取 skill 定义”或“确认已加载 skill”。

2.4 最小可用性校验

第一次使用前，建议至少做下面检查：

uv run python scripts/factory-dispatch --help
uv run python scripts/factory-init --help
uv run python scripts/factory-agent-session --help

只要帮助信息能正常输出，说明最基本的脚本入口是可用的。

补充说明：

  • 当前仓库正式基线是 Python 3.14+ + uv
  • 推荐入口是 uv run python scripts/...
  • 系统 python3 只适合做临时探测，不再作为正式工作流基线

3. 先理解两个目录不是一回事

很多新手第一次会混淆下面两个目录：

  • shanforge 仓库：工具、脚本、技能、文档所在位置
  • 目标项目：你真正要初始化、纳管、维护的业务项目

通常是：

  • 你站在 shanforge 仓库里调用命令
  • 命令再通过 --project 或 --path 指向业务项目

所以你写 Prompt 时，项目路径一定要说清楚。

4. 开始前最重要的一步：先判断项目类型

不要一上来就说“帮我启动项目”。

你要先判断当前项目属于下面哪一种。

类型 A：空目录新项目

特征：

  • 你准备创建一个全新项目
  • 目标目录是空的

这类项目通常先做初始化。

类型 B：已有代码仓库，但还不是软件工厂项目

特征：

  • 已经有代码、配置、README、部署方式
  • 但没有完整的软件工厂骨架

这类项目通常先纳管，再进入正式维护。

类型 C：已经纳入软件工厂的项目

特征：

  • 根目录已有项目规则入口
  • 已有内部控制面
  • 有阶段化 docs/

这类项目通常直接从当前阶段继续推进。

类型 D：半初始化项目

特征：

  • 已经有 docs/
  • 已经有部分运行痕迹
  • 但项目规则入口还不完整

这类项目通常是补齐规则入口，而不是重新初始化。

5. 为什么这一步必须先判断

因为不同类型的项目，第一步完全不同：

  • 新项目：通常先 factory-init
  • 历史项目：通常先建立当前真实状态基线，再纳管
  • 已纳入项目：通常先读取规则和当前状态
  • 半初始化项目：通常先补齐规则入口

如果这一步判断错了，后面很容易出现下面这些问题：

  • AI 把已有项目当空目录重建
  • AI 还没纳管就开始写代码
  • AI 以为项目已经完整初始化，但其实规则入口缺失
  • 文档和项目状态越来越不一致

6. 先看懂几类资产

第一次使用时，你不需要看懂所有目录，但一定要明白下面几类资产的边界。

正式文档

docs/ 放的是给人读的正式事实源：

  • 需求
  • 设计
  • 计划
  • 测试
  • 发布
  • 运维
  • 用户文档

这是人类默认阅读入口。

项目规则入口

根目录的项目规则入口负责约束 AI 的协作方式、阅读顺序和长期边界。

它的职责是“约束 AI 怎么工作”，不是“给人上手项目的教学文档”。

不应该写进去的内容：

  • 当天构建失败
  • 临时依赖问题
  • 当前运行异常

内部控制面

项目还会维护一套 AI 自用的内部控制面，用来承载运行时状态、压缩摘要、最近阻塞和过程记录。

它的职责是帮助 AI 低成本接手，不是给人类当阅读目录。

一句话记忆：

  • 人类默认看 docs/
  • AI 默认看项目规则入口和内部控制面
  • 正式事实写进 docs/
  • AI 摘要只做压缩和回放，不替代正式文档

7. 第一轮会话的标准开法

第一次真正开始工作时，Prompt 至少要带上下面四类信息：

  1. 项目路径
  2. 项目当前状态
  3. 第一优先动作
  4. 不要做什么

最容易失败的说法是：

帮我用 shanforge 初始化一个项目，项目想法是……

问题在于它没有说清楚：

  • 路径
  • 是空目录还是已有仓库
  • 必须先做什么
  • 不能做什么

更稳妥的开法通常长这样：

项目路径是：/path/to/project

这是一个空目录新项目。
请先执行 `factory-init`，不要手工生成一套伪初始化文档。
初始化完成后，列出关键产物，再进入需求阶段。
如果目录非空，不要继续初始化，先告诉我应该改走哪个入口。

更完整的模板看 提示词速查。

8. 四种典型情况该怎么开始

8.1 空目录新项目

标准顺序：

  1. 明确项目路径、项目名、核心创意、技术栈倾向
  2. 明确要求 AI 先执行 factory-init
  3. 初始化完成后检查关键产物
  4. 再进入需求阶段

你应该检查的产物：

  • 是否真的执行了初始化动作
  • docs/ 下关键入口是否已经生成
  • 项目规则入口是否存在
  • 常用脚本入口是否可用

8.2 历史项目纳管

标准顺序：

  1. 不要把它当空目录新项目
  2. 先让 AI 基于当前代码、配置、现有文档、运行方式建立真实状态基线
  3. 再补齐软件工厂骨架
  4. 纳管完成后再进入 BUG / CR / TASK

你应该检查的结果：

  • 当前真实状态摘要是否清楚
  • 当前阶段判断是否合理
  • 正式文档、项目规则入口和内部控制面是否已经补齐

8.3 已纳入软件工厂的项目

标准顺序：

  1. 先让 AI 按项目规则入口、当前状态摘要和相关正式文档读取必要上下文
  2. 再进入当前阶段工作
  3. 如果不确定下一步，先做诊断

推荐开场：

这个项目已经纳入软件工厂。
请先读取规则入口和当前状态，然后继续处理下面这件事：……

8.4 半初始化项目

标准顺序：

  1. 先检查已有正式文档、项目规则入口和当前状态摘要；只有判断缺口时再单文件回源受影响 docs/
  2. 判断是“规则入口缺失”还是“纳管未完成”
  3. 如果适用，优先使用 factory-project-rules-refresh
  4. 再执行 factory-state-doctor 和阶段检查

不要做的事：

  • 不要把它当空目录重建
  • 不要重写整套现有文档

8.5 已纳管项目按新规范重构 docs

标准顺序：

  1. 先确认项目已经被山海工枢接管，也就是已有正式文档、项目规则入口和内部控制面
  2. 激活 document-templates skill，按 4 大模块手工重构 docs/
  3. 完成后执行 uvx --from docs-stratego docs-stratego source validate --repo-path "."
  4. 再执行 factory-state-doctor --scope docs
  5. 人工复核根 docs/index.md、相关目录 index.md、access 例外和契约页纳入情况

推荐开场：

这个项目已经纳入软件工厂。
请使用 `document-templates` skill 按最新山海工枢源文档标准重构 `docs/`，并在完成后执行 `docs-stratego source validate`，告诉我最终是否为 `就绪`。

这类场景对应的可复制模板，直接看 提示词速查。

8.6 统一通知多个项目负责人校验 docs

标准顺序：

  1. 先确认每个项目都已经由负责人用 document-templates skill 调整过 docs/
  2. 为每个项目负责人生成统一通知，要求他们在各自仓库执行 docs-stratego source validate
  3. 区分“已通过校验”和“仍需补文档/修导航”的项目
  4. 收齐反馈后，再决定是否需要集中复核导航和契约页

不要做的事：

  • 不要在平台仓库里直接替每个业务项目手工改 docs
  • 不要继续使用 factory-docs-* 旧命令

如果你需要直接转发的自然语言通知模板，看 提示词速查。

9. 日常使用的推荐节奏

会话开始时

  • 先判断项目类型
  • 先让 AI 读取规则和当前状态
  • 先做诊断，再推进动作

会话中途

  • 如果目标变化，明确是 BUG、CR 还是 TASK
  • 如果进入实现，要求 AI 同步更新代码、测试、文档和记忆
  • 如果感觉 AI 开始“凭感觉发挥”，让它先回到当前正式状态

会话结束时

  • 检查本轮改动是否同步到 docs/
  • 检查内部控制面摘要是否更新
  • 必要时要求生成一次 factory-state-doctor
  • 发布前要求生成 factory-stage-check / factory-quality-check

10. 什么时候应该优先做诊断

出现下面任一情况时，不要继续盲推：

  • 你不知道当前阶段
  • 你不确定项目到底有没有纳入软件工厂
  • AI 读错上下文
  • 规则入口缺失
  • 项目已经有 docs/ 和部分运行痕迹，但你不确定该补还是该重建

这时优先让 AI：

  • 先生成一次 factory-agent-session
  • 再执行一次 factory-state-doctor

11. 新手最常见的错误

错误 1：不写项目路径

后果是 AI 很容易在错误目录工作，或者只开始“写方案”。

错误 2：已有仓库还强行当空目录初始化

后果是项目状态会越来越乱。

错误 3：把临时状态写进项目规则入口

后果是规则入口越来越脏，AI 每次都会读到过期信息。

错误 4：只改代码，不更新文档和记忆

后果是软件工厂的正式事实源失真。

错误 5：一句话同时要求初始化、需求、设计、实现全部做完

后果是任务过大，结果通常既不细也不稳。

12. 你做完一轮操作后应该检查什么

如果你刚初始化新项目

检查：

  • 是否真的执行了初始化动作
  • 项目规则入口、内部控制面和 docs/ 是否存在

如果你刚完成纳管

检查：

  • 当前阶段是否明确
  • 当前真实状态是否被写清楚
  • 后续应该从 BUG、CR、TASK 哪一种开始

如果你刚刷新了 docs 标准

检查：

  • docs-stratego source validate 最终是否为 就绪
  • 根 docs/index.md 和相关目录 index.md 是否已经刷新
  • openapi / tools 契约页是否正确纳入导航
  • 是否还有需要人工复核的导航顺序、标题或 access 例外

如果你刚推进了需求或设计

检查：

  • 正式文档是否更新
  • 是否还留着明显占位内容
  • 是否已经可以进入下一阶段

如果你刚推进了实现

检查：

  • 代码、测试、文档和内部控制面摘要是否同步
  • 是否明确关联了工作项

13. 下一步看什么