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
devflow codemcp --help

初始化流程

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

devflow init

开始时会选择代码智能工具：

1. codebase-memory-mcp（默认）
2. CodeGraph
3. 两个都安装

交互终端会显示复选框：用方向键移动、空格切换勾选、Enter 确认。codebase-memory-mcp 默认已勾选；全部取消后按 Enter 会直接退出。在非交互环境中，Devflow 同样默认使用 codebase-memory-mcp。选择两个工具时，始终先处理 codebase-memory-mcp，再处理 CodeGraph。

命令会依次完成：

1. 检查运行环境并配置所选代码智能工具：codebase-memory-mcp 与 CodeGraph 都优先通过 npm 全局安装；npm 安装 Codebase Memory 后会运行其原生安装命令，自动检测并配置它支持的 AI 客户端。若 npm 失败，Codebase Memory 会改用官方安装脚本，CodeGraph 会询问是否改用官方安装脚本。两者都会检查更新，发现新版本时询问是否更新，非交互环境默认跳过并给出提醒。选择 CodeGraph 时，还会为 Claude Code、Cursor、Codex 和 OpenCode 安装其全局集成。
2. 把 archer-workspace.git 克隆到当前目录的 archer-workspace/；已存在工作区时，仅在顶层及已存在的子仓库都没有本地业务改动的情况下执行快进更新。
3. 临时拉取 archer-docs.git，把完整 openwiki/ 目录更新到 archer-workspace/devflow/openwiki/，然后删除临时仓库。
4. 按选择的工具为 archer-workspace/ 构建代码智能索引，spinner 会实时展示索引进度；完成后清除状态。

CLI 会以 [1/4] 到 [4/4] 显示中文等待状态。前 3 步完成后会保留成功提示；第 4 步（代码智能索引）的进度信息会实时更新在同一条 spinner 上，完成后自动清除。安全检查、OpenWiki、索引或意外命令错误会立即停止并以非零退出码结束。

devflow init 不会同步 Git 子仓库。如需同步，请在工作区根目录手动运行 bash sync-submodules.sh。

单独准备当前目录的代码智能工具

在任意 Git 仓库或需要建立索引的目录中运行：

cd /path/to/repository
devflow codemcp

该命令只检查、更新和配置所选的代码智能工具，并为当前目录建立索引；不会克隆或更新 Archer 工作区、OpenWiki 或子仓库。它使用与 devflow init 相同的选择菜单，默认 codebase-memory-mcp，非交互环境也使用该默认值。选择两个工具时先处理 codebase-memory-mcp，再处理 CodeGraph。

索引状态根据实际数据库文件判断，而不是仅检查目录是否存在：

• codebase-memory-mcp：Devflow 会以 persistence=true 显式索引并写出 .codebase-memory/graph.db.zst；已有该文件时更新索引，文件不存在时初始化。索引缓存位于 .codebase-memory/cache/，并会自动创建 .codebase-memory/.gitignore 忽略该目录内的索引产物；已有自定义忽略规则时不会覆盖。
• CodeGraph：已有 .codegraph/codegraph.db 时执行 codegraph sync 更新索引；文件不存在时执行 codegraph init 初始化。

两种工具都会在执行前检查更新；若发现可用更新，会在交互环境询问确认，非交互环境则跳过更新并继续使用现有版本。

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。

子仓库同步

devflow init 不会调用子仓库同步脚本。需要同步或在权限开通后重试时，请在工作区手动执行：

cd archer-workspace
bash sync-submodules.sh

该脚本只负责同步 Git 子模块，不会安装或调用任何代码智能工具。同步完成后，如需更新索引，请在工作区根目录执行 devflow codemcp 并选择要使用的工具。

本地改动保护

更新既有工作区前，Devflow 会检查顶层及已存在的递归子仓库，避免在本地业务改动尚未处理时执行快进更新。

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

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

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

重复执行

• archer-workspace/ 不存在：克隆 master。
• 已存在且干净：执行 git pull --ff-only origin master。
• origin 或当前分支不匹配：停止并提示用户处理。
• codebase-memory-mcp：显式索引会持久化 .codebase-memory/graph.db.zst；该文件已存在时更新索引，文件不存在时初始化。.codebase-memory/.gitignore 会忽略本地索引产物，缓存位于 .codebase-memory/cache/。
• CodeGraph：.codegraph/codegraph.db 已存在时执行 codegraph sync 更新索引；只有空目录或 .gitignore 时执行 codegraph init。

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

开发验证

npm test
npm run typecheck
npm run build