安装排错

先顺着这张表往下走——大多数报告对得上这六行之一。

症状	修法
`npm i` 之后没有 `/flow`	跑 `npx @manhquy/flow-skill@latest`。必须执行这个 CLI；光装包不会往 skill 家目录拷任何东西。
“重装”之后还是旧 skill	永远用 `@latest` 拿 skill v0.34.4（installer 0.7.11）。裸包名可能被 npx 缓存 serving。
Claude 或 Codex 不列这个 skill	首次安装后把 agent 彻底重启一次。
PowerShell 报 `flow.sh: No such file`	调 `…/runner/flow.cmd`，别调 `bash`。
`durable layer DISABLED`	装 `python3`，或无视——机械 gate 照跑。
CRLF 或 “bad interpreter”	仓库用 `.gitattributes` 强制 LF；行尾被搞坏就重 clone。

先跑 doctor

bash ~/.claude/skills/flow/runner/flow.sh doctor

doctor 检查 bash、python、grep、git，报告它看得到的安装路径。READY 说明环境没问题，毛病在别处——通常是 agent 没重启。

“装了但没有 /flow”

两个不同原因，按可能性排序。

你装了包，没运行它。 npm i @manhquy/flow-skill 是往 node_modules 加包，不往 agent 找的任何地方拷 skill 树。installer 是拿来执行的 CLI：

npx @manhquy/flow-skill@latest

你没重启 agent。 agent 启动时枚举 skill 目录。Claude Code 要重启；Codex 要重启再加 $flow 而不是 /flow；Cursor 和 Antigravity 要 reload 工具或 IDE。

确认文件真落盘了：

ls ~/.claude/skills/flow/SKILL.md

“装了个旧版本”

信机器，别信文档，看你到底装了什么：

npx @manhquy/flow-skill@latest --help
# --help 打印两个数字：installer CLI，和它带的 skill 产品

grep -E '^\s*version:' ~/.claude/skills/flow/SKILL.md | head -1

装好的 skill 版本比 --help 报的旧，说明复制没到那个家目录——重跑 installer，明确选 agent。

两种 pin 错造成大多数过期安装：

pin 了 skill 产品版本号在 npm 上。那数字不是发布的包版本。pin installer CLI 版本，或用 @latest 拿当前 skill。
用了 @rc tag。它退役了，过期了。

npm 报 No matching version found，就是 pin 了 skill 产品号。用 @latest 或 pin installer。两个数字为什么不一样在两个版本号。

Windows：PowerShell 解析错 bash

PowerShell 或 cmd 里——包括 Codex 里——裸 bash 通常解析到 WSL 的 C:\WINDOWS\system32\bash.exe。WSL 读不了 C:/... 或 /c/... 路径，报 No such file or directory，harness 明明没坏看着像坏了。

用 launcher，它找得到 Git Bash，传它认的路径：

& "$env:USERPROFILE\.codex\skills\flow\runner\flow.cmd" status

确认 bash 是 Git Bash 之前，别直接 bash flow.sh。

“durable layer DISABLED”

这是降级模式，不是失败。持久层是 Python 加 SQLite，存 intake、story、trace、decision、backlog 记录。没有 python3，机械 gate 和每个 stage、card 检查照跑——只是跨 session 记忆没了，/flow recall 能读回的东西变少。装 python3 重新打开它。

还卡着

求助前收集三样：完整 doctor 输出、--help 打印的两个版本号、原样的命令和报错原文。去 github.com/manhquydev/flow-skill 开 issue。

备选安装路

npm installer（npx @manhquy/flow-skill@latest）是 skill v0.34.4 的推荐路。备选给 contributor 和 air-gapped 机器。

从 git checkout：

bash install.sh global          # 或 Windows 上：pwsh install.ps1 global
bash install.sh project [dir]   # 项目级 Claude skill

bash install.sh global 同步所有检测到的 agent 家目录并跑 doctor。bash install.sh project [dir] 装项目级 Claude skill。Windows 用 pwsh install.ps1 global，因为 PowerShell 里裸 bash 通常是 WSL，读不了 Windows 路径。

Claude Code 也可以把仓库加为 plugin marketplace，装 flow@flow-marketplace。

全手动路是把 skills/flow/ 拷到 ~/.claude/skills/flow/，runner/flow.sh 加执行位。每条通道写同一棵树，项目换通道不用重过 gate、重切 card。

命令和平台说明：README.md

安装 CLI flag

npx @manhquy/flow-skill@latest

要 Node.js 22.14 或更高。永远带 @latest（带 skill v0.34.4）——裸 npx @manhquy/flow-skill 可能被 npx 缓存 serving，重跑旧拷贝。

照抄，别转述 flag 意思。--project 只对 claude 有效。

npx @manhquy/flow-skill@latest --yes
npx @manhquy/flow-skill@latest --yes --target claude
npx @manhquy/flow-skill@latest --yes -t claude -t codex
npx @manhquy/flow-skill@latest --yes --all
npx @manhquy/flow-skill@latest --yes --project --dir .
npx @manhquy/flow-skill@latest --yes --all --dry-run --json

flag	意思
`-y`、`--yes`	跳过提示；装默认选择（检测到的 + Claude）
`-t`、`--target <name>`	目标（可重复或逗号分隔）
`--all`	全目标，没检测到也装
`--project`	项目级——只 Claude → `<dir>/.claude/skills/flow`
`--dir <path>`	项目目录（蕴含 `--project`；默认 cwd）
`--json`	JSONL 事件（`plan`、`install:*`、`summary`）
`--dry-run`	只打印计划；不写
`-h`、`--help`	帮助。`--help` 打印两个版本号。

--project 只支持 claude。别的 target 加 --project exit 2。

做	别做
`npx @manhquy/flow-skill@latest`	裸 `npx @manhquy/flow-skill`（npx 缓存过期）
运行 CLI 来复制 skill	光 `npm i`（只有包；agent 家目录没 skill 文件）
需要就 pin installer `@0.7.11`	pin npm `@0.34.4`（skill 版本 ≠ 包版本）
用 `@latest`	`@rc`（退役 / 过期）

包：npm 上的 @manhquy/flow-skill。flag 意思跟着 installer 走：npm-wrapper/README.md。

安装路径

installer 把同一棵 skill 树拷进你选的每个 agent 家目录。家目录之间不共享——每个都是完整拷贝。

按 agent

Agent	路径	调用
Claude Code	`~/.claude/skills/flow`（或项目级 `.claude/skills/flow`）	`/flow`
Codex CLI	`~/.codex/skills/flow`	`$flow`——装完重启 Codex
Agents home	`~/.agents/skills/flow`	看 host
Antigravity	`~/.gemini/antigravity-cli/skills/flow`（CLI）和 `~/.gemini/config/skills/flow`（IDE）	`/flow`，reload 之后
Cursor	`~/.cursor/skills/flow`	agent skills 面板，reload 之后

Antigravity 有两个家，因为 CLI 和 IDE 读不同目录。同一个 SKILL.md 包两份；跑 agy inspect 确认被发现了。

skill 家目录里有什么

路径	内容
`SKILL.md`	语义层入口：分发、守门、编排。带 `metadata.version`。
`runner/flow.sh`	机械引擎。`runner/flow.cmd` 是 Windows launcher。
`harness/`	持久层（Python 加 SQLite）。
`law/`	`CLAUDE.md` 构建会话法、`DESIGN.md` UI 法、`RETRO.md`。
`references/`	语义 playbook：gate 规则、concierge、项目类型、agent 映射等。
`_templates/`	runner 拷进项目的 gate 产物模板。运行中别改。
`playbooks/`	技术栈知识——在那个栈上构建前读，构建后收割。

项目文件去哪

skill 家目录装 harness。项目装活，在你运行的目录下：

flow/00-idea.md .. 05-contract.md   规划产物，带 gate
cards/C-NNN.md                      交付单元
MODE, PROJECT_TYPE                  起草模式和项目类型
RETRO.md, DEBT.md, AUTO-LOG.md      台账
DESIGN.md                           项目 UI 法
.flow/harness.db                    持久记录

FLOW_PROJECT_ROOT 覆盖项目根。在没自己 flow/ 的子目录运行，认最近祖先的 flow 项目，往 stderr 打印一行说明，不另起 fragmented 的第二根。

跨项目知识库

/flow promote <playbook.md> 把 playbook 拷到 ~/.claude/flow/playbooks，/flow recall 在每个项目都能翻到它，不只在学到它的地方。

运行时依赖

依赖	干什么用
`bash`	机械引擎。Windows 上指 Git Bash——用 `runner/flow.cmd`。
`python3`	推荐。驱动持久 harness。没有它 gate 照跑，SQLite 层关掉。
`git`	可选。worktree 和 `/flow auto` 要它。
Node.js ≥ 22.14	只给 npm installer，skill 运行时不要。

验一个家目录

grep -E '^\s*version:' ~/.claude/skills/flow/SKILL.md | head -1
bash ~/.claude/skills/flow/runner/flow.sh doctor

环境变量

runner 读一批 FLOW_* 变量。下面是日常用的；全集在 runner 源码里定义。

变量	效果
`FLOW_PROJECT_ROOT`	覆盖项目根，不走目录上溯。
`FLOW_SESSION_ID`	稳定 session 标识。每个 session 导出一次，每次调用都带，得到硬并发保护而不是告警。
`FLOW_LOCK_TTL`	`flow/.lock` 自动回收秒数。默认 900。
`FLOW_FORCE`	设 `1` 接管你确定死了的锁。
`FLOW_LOG_DISABLE` / `DO_NOT_TRACK`	关本地 JSONL usage 日志（`/flow usage` 卷它的）。反正只在本地。
`FLOW_EVAL_RETRY_BACKOFF`	计费 eval 批的重试 backoff 秒数。默认 5；测试里设 0。

不带 FLOW_SESSION_ID，runner 证明不了竞争的是不同 session，只能告警不拦——所以共享机器上导出它很重要。

权威定义：skills/flow/runner/flow.sh

两个版本号

flow 发两个版本号，对不上。这是故意的，不是漂移。--help 打印两个数字。信你机器上的，别信文档里的。

哪个	版本化什么
skill 产品	gate、`SKILL.md`、runner、reference、模板——审判你构建的那个东西。活在 `SKILL.md` metadata 里。
npm installer	`@manhquy/flow-skill` CLI，把 skill 拷进 agent 家目录的那个。活在 npm 包上。

npx @manhquy/flow-skill@latest --help
# flow-skill v0.7.11 (ships skill v0.34.4)

grep -E '^\s*version:' ~/.claude/skills/flow/SKILL.md | head -1

为什么两个数字

版本化的东西不一样，变化频率不一样。

  monorepo skills/flow/  --npm run sync-->  npm-wrapper/skills/flow  --npm pack-->  registry
         |                                         |
         | install.sh / agent skill homes          | npx @manhquy/flow-skill@latest
         v                                         v
  ~/.claude/skills/flow                     same tree via installer CLI

skill 产品是 harness 本人。它的版本驱动一致性检查和持久层里记的 telemetry 字段，项目永远能说清自己在哪套 gate 语义下构建。gate、stage、reference playbook 一变它就变——经常变。

npm 包只版本化 installer CLI：agent 检测、交互多选、文件拷哪、flag。这个面小而稳。gate 规则变了就发新 installer 版本，是谎报变了什么，还逼用户琢磨一个说明不了问题的数字。

合二为一，要么 gate 一变就 bump installer，要么 gate 版本被 installer 发版节奏冻住。两个都比解释一张表差。

它造成的错，以及怎么避开

失败模式是 pin 错数字。skill 产品版本不是发布的 npm 包版本。要定版就 pin installer CLI。几乎所有人：@latest 最好。

# 错——pin skill 产品版本（它不是 npm 包版本）
# 对——pin installer CLI 版本，或用 @latest 拿当前 skill
npx @manhquy/flow-skill@latest

现在最新的 skill 在 @latest 上（0.7.11 带 skill 0.34.4）。裸 npx @manhquy/flow-skill 可能被 npx 缓存 serving，悄悄重跑旧拷贝。@rc tag 退役了，别用。

npm 报 No matching version found，八成 pin 了 skill 产品号。--help 打印两个数字；pin installer 那个。

哪个数字跟你有关

用 flow，skill 产品版本描述你的体验——告诉你有哪套 gate、哪些命令。installer 版本只在你调安装或定版构建时重要。

报问题，两个都给。--help 一行全打印，这行就是为这个存在的。

查项目里的漂移

/flow coherence

标出各版本声明字段之间的漂移——漂移格里文档对代码的便宜切片。建议性质：只标，不自动修。

安装与首次运行 · 更新日志