Skip to content

docs: verify latest installs and document command catalog - #11

Merged
Innocent-children merged 44 commits into
mainfrom
docs/improve-project-positioning
Aug 22, 2026
Merged

docs: verify latest installs and document command catalog#11
Innocent-children merged 44 commits into
mainfrom
docs/improve-project-positioning

Conversation

@Innocent-children

@Innocent-children Innocent-children commented Aug 22, 2026

Copy link
Copy Markdown
Owner

问题

现有安装文档存在三个需要统一处理的问题:

  1. 面向普通用户的安装示例固定为已经发布的精确版本,后续发布后容易长期停留在旧版本;
  2. Codex、DeepSeek、packaged Core、selector 与 MCP tool 的调用入口分散在多份文档中,缺少一份对照实际实现的完整命令目录;
  3. 对照代码检查时发现两处真实不一致:Codex remove 输出的 npm 卸载命令缺少全局参数 -g,Core help 仍显示已取消治理的内部名称 Core Contract 0.2

修改

使用 npm latest 安装

所有面向普通用户的安装示例统一使用:

npm install -g dev-flow-codex@latest
TARBALL="$(npm pack dev-flow-deepseek@latest --silent)"

同步范围包括:

  • 9 个根 README locale;
  • Codex / DeepSeek 中英文 package 文档;
  • 中英文命令参考与 I18n 治理文档。

Support Matrix、Release Tag、npm 精确版本链接、bundled Core identity 与最终制品证据继续保留 0.5.1 / 0.5.0 等精确身份,不使用 latest 替代不可变证据。

对照实现建立完整命令目录

新增:

  • docs/COMMANDS.md
  • docs/COMMANDS_en.md

命令目录按调用层分开说明:

  • Codex 用户命令:setup [--json]remove [--json]--version
  • Codex managed Host 命令:mcp
  • DeepSeek DSH 生命周期:版本检查、npm pack @latest、profile add、--dump-config、profile remove;
  • Codex 与 DeepSeek 的对话 selector;
  • packaged Core 完整 CLI:help 形式、versionmcp --stdio
  • 六个 MCP tool 的读写类型和用途。

命令事实分别对照:

  • packages/*/package.json 的 package、bin 与平台约束;
  • packages/codex/bin/dev-flow-codex.mjs 的实际参数 parser;
  • DeepSeek lifecycle tests 与最终 registry Journey;
  • cmd/dev-flow/main.go
  • internal/mcp/ 的闭合 tool catalog。

文档明确指出 dev-flow-deepseek 没有独立 bin,并且不会记录实现不接受的 Codex helpupdateuninstall 或其他推测子命令。

修正代码与输出一致性

  • dev-flow-codex remove 的后续提示从:

    npm uninstall dev-flow-codex
    

    修正为:

    npm uninstall -g dev-flow-codex
    

    同步更新 launcher 定向测试。

  • Core help 从 governed Core Contract 0.2 改为 governed Core,移除已经取消治理的内部合同版本号,并只修改对应帮助断言。

  • packages/codex/tests/launcher.test.mjs 加入仓库 bounded validation,确保 Codex 命令 parser、版本输出、setup/remove 行为、未知命令拒绝和全局卸载提示在普通 PR CI 中执行。

文档与 I18n 治理

  • AGENTS.md 现在要求安装与命令文档对照实际 parser、manifest、Journey 和 MCP catalog;
  • 命令变化必须在同一 checkpoint 更新 docs/COMMANDS*、受影响的 package README 与全部相关根 README locale;
  • 公开安装示例使用 @latest,精确支持与发布证据继续使用不可变版本;
  • 同步更新 docs/I18N*CONTRIBUTING* 和 Pull Request 模板。

明确范围外

  • 不新增或删除 CLI 子命令、selector、Core transport 或 MCP tool;
  • 不改变 Task、状态图、SQLite、Recovery 或 Host Adapter 的流程语义;
  • 不修改 Core、Codex 或 DeepSeek 产品版本;
  • 不扩大平台、Host 兼容范围或 Support Matrix 声明;
  • 不发布 npm,不创建 Tag,不操作 GitHub Release;
  • 不合并本 Pull Request。

验证

当前 Head:39b0603d1519562071e088d3c5f0cf708337a3d9

GitHub Actions pull-request-validation run #111 已通过,包含:

  • Codex package contract:9/9 passed;
  • Codex launcher command contract:10/10 passed;
  • DeepSeek package / Adapter contracts:33 passed,2 个平台相关检查按预期 skipped;
  • DeepSeek simulated graph journey:passed;
  • Codex / DeepSeek release contract tests:passed;
  • go vet ./...:passed;
  • go test ./...:passed,包括 cmd/dev-flow
  • Codex package dry-pack:passed;
  • 最终结果:Repository validation passed.

另外使用本地 npm fixture 验证了 npm pack <package>@latest --silent 仍在 stdout 返回 tarball 文件名,因此 TARBALL="$(...)" 安装形式成立。

I18n

已同步:zh-CNenzh-TWjakoesfrdept-BR

9 个根 README 保持相同的安装命令、selector、MCP tool catalog、状态图拓扑、精确支持身份和命令参考入口。新增翻译已完成结构与技术事实同步;合并前仍建议由对应语言的母语开发者进行措辞 review。

@Innocent-children Innocent-children changed the title docs: improve project positioning and contribution path docs: explain Dev Flow through AI coding pain points Aug 22, 2026
@Innocent-children Innocent-children changed the title docs: explain Dev Flow through AI coding pain points docs: adopt technical positioning and README i18n policy Aug 22, 2026
@Innocent-children Innocent-children changed the title docs: adopt technical positioning and README i18n policy docs: verify latest installs and document command catalog Aug 22, 2026
@Innocent-children
Innocent-children merged commit c6488b9 into main Aug 22, 2026
1 check passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant