Devflow CLI

一个专门用于初始化 Archer 研发工作区的中文命令行工具。

环境要求

• macOS 或 Linux
• Node.js 20+
• Git

安装

npm install -g devflow-xd-cli

本地安装

# 拉取仓库
npm install
npm run build
npm link

安装后可检查中文帮助：

devflow --help
devflow init --help

初始化流程

在希望存放 Archer 工作区的目录中运行：

devflow init

命令会依次完成：

1. 检查 CodeGraph CLI；未安装时优先执行 npm install -g @colbymchenry/codegraph@latest，npm 失败后询问是否改用官方安装脚本；已安装时检查最新版本。
2. 发现新版本后询问是否更新；非交互环境默认跳过并给出提醒。
3. 为 Claude Code、Cursor、Codex 和 OpenCode 安装全局 CodeGraph 集成。
4. 把 archer-workspace.git 克隆到当前目录的 archer-workspace/。
5. 已存在工作区时，仅在顶层及全部已有子仓库都没有本地业务改动的情况下执行快进更新。
6. 临时拉取 archer-docs.git，把完整 openwiki/ 目录更新到 archer-workspace/devflow/openwiki/，然后删除临时仓库。
7. 同步所有子仓库，期间 spinner 会实时展示当前仓库与同步进度；全部成功后清除状态，仅子仓库无访问权限时保留失败提示并继续后续步骤。
8. 构建 CodeGraph 索引，spinner 同样实时展示索引进度；完成后清除状态。

CLI 会以 [1/5] 到 [5/5] 显示中文等待状态。前 3 步完成后会保留成功提示；第 4 步（子仓库同步）和第 5 步（CodeGraph 索引）的进度信息会实时更新在同一条 spinner 上，完成后自动清除。安全检查、OpenWiki 或意外命令错误会立即停止；仅子仓库无访问权限时会记录失败仓库，继续同步其余仓库并完成 CodeGraph 索引，最终以退出码 1 提醒用户仍有待处理项。

OpenWiki 更新

• 来源：archer-docs/openwiki/
• 目标：archer-workspace/devflow/openwiki/，保留外层 openwiki 目录。
• 来源和目标 openwiki/.last-update.json 完全一致时跳过复制。
• 文档有更新时替换旧文档并清理已删除的文件，但保留本地 devflow/artifacts/。
• 从旧平铺结构首次迁移时会清理 devflow/ 下旧文档，只留下 artifacts/ 和新的 openwiki/。
• 临时拉取目录无论成功或失败都会清理。

单独更新 OpenWiki

可以在 Archer Workspace 根目录、任意子目录或其父目录执行：

devflow openwiki

命令会自动定位 archer-workspace 并比较 marker。OpenWiki 没有变化时只提示“已是最新”；实际更新后会自动刷新 CodeGraph：已有 .codegraph/codegraph.db 时执行 codegraph sync，未初始化时执行 codegraph init。

子仓库权限不足

某个子仓库无法拉取时，CLI 会列出仓库路径和地址，并提示申请 GitLab 权限。其余可访问仓库和 CodeGraph 索引仍会继续处理。

权限开通后，在工作区手动执行：

cd archer-workspace
bash sync-submodules.sh

脚本检测到 codegraph 命令后会自动重新索引：没有 .codegraph/codegraph.db 时执行 codegraph init，数据库存在时执行 codegraph sync。仅有 .codegraph/ 目录不代表已经初始化。通过 devflow init 调用脚本时，脚本内索引会被跳过，仍由 CLI 的 [5/5] 统一执行，避免重复索引。

本地改动保护

sync-submodules.sh 可能重置已有子仓库，因此 Devflow 会在调用脚本前检查顶层和递归子仓库。

发现未提交或未跟踪文件时，命令会列出相关仓库并停止：

以下仓库存在本地改动：
  - frontend/example-react
请先提交、暂存或清理这些改动后再重试。

同步前还会核对子仓库的 origin、声明分支以及相对 origin/<branch> 的未推送本地提交，避免同步脚本覆盖本地提交。

父仓库中仅由子仓库 HEAD 更新产生的 Gitlink 状态（例如 modules/business (new commits)）不会被视为业务代码改动；Devflow 会递归进入对应子仓库，单独检查其中真正的未提交、未跟踪文件，因此不会放松对子仓库本地代码的保护。

重复执行

• archer-workspace/ 不存在：克隆 master。
• 已存在且干净：执行 git pull --ff-only origin master。
• origin 或当前分支不匹配：停止并提示用户处理。
• .codegraph/codegraph.db 已存在：执行 codegraph sync 更新索引；只有空目录或 .gitignore 时执行 codegraph init。

修复错误后可以安全地重新运行 devflow init。

开发验证

npm test
npm run typecheck
npm run build