feat: add flow2spec doctor command

.Knowledge/index.md

@@ -37,6 +37,7 @@
 | f2s-dev-workflow-constraints | `.Knowledge/topics/f2s-dev-workflow-constraints.md` | 开发工作流约束（仅 Flow2Spec 本仓自身，不给下游）：只改 templates / 不改配置根 / 用户驱动分发 | 长文：`rules/repo-dev-workflow-constraints.*`；自查技能：`skills/repo-dev-check/SKILL.md` |
 | f2s-kb-distill | `.Knowledge/topics/f2s-kb-distill.md` | Q&A 驱动知识提取；自动判断创建新 topic 或追加现有 topic | 技能：skills/f2s-kb-distill/SKILL.mdc |
 | flow2spec-init-defaults | `.Knowledge/topics/f2s-init-defaults.md` | `flow2spec init` 字段默认值、四处落点一致性、老项目缺字段补写、`init` 不动 stock/req/topics/matchers、manifest 两个版本字段（`projectRev` / `pkgRev`）对照 | 包源码：`lib/flow2specConfig.js` `DEFAULTS` / `CONFIG_FIELDS`；模板：`templates/{locale}/flow2spec.config.json` |
+| flow2spec-doctor | `.Knowledge/topics/flow2spec-doctor.md` | `flow2spec doctor` 只读检查环境、项目初始化、协作上下文与知识库健康 | stock：[Doctor 诊断命令](stock-docs/Flow2Spec-doctor诊断命令.md)；中英文命令文档：`docs/命令说明.md` / `docs/en/commands-reference.md` |
 
 每主题保留 **1–3 条** 可点击摘要链接；全量路径对照写入 `.Knowledge/migration-report.md`（迁移场景）。  
 其中 **`implement-tech-design`**、**`f2s-doc-routing`**、**`config-precheck`**、**`f2s-task`** 在 `topics/` 内为**路由摘要**；执行长文见配置根 **`rules/f2s-*.md(c)`**；使用 Codex 时见 **`.codex/AGENTS.md`**、**`.codex/topics/f2s-*.md`**（`f2s-config-check` 与 `AGENTS` 前置同源，按需打开）。**`f2s-knowledge-preflight`** 与 **`f2s-kb-feedback-closing`** 是普通问答首读 / 源码补答收口门禁，作为配置根规则 / Codex 专题长文生效，不写入 `topicPaths` 或 `taskToTopicRules`；**`f2s-kb-feedback-closing`** 在 cases 1–3 建议执行 **`f2s-kb-distill`**。

.Knowledge/manifest-routing.json

@@ -32,7 +32,8 @@
     "f2s-dev-workflow-constraints": ".Knowledge/topics/f2s-dev-workflow-constraints.md",
     "f2s-kb-distill": ".Knowledge/topics/f2s-kb-distill.md",
     "flow2spec-init-defaults": ".Knowledge/topics/f2s-init-defaults.md",
-    "flow2spec-collaboration": ".Knowledge/topics/flow2spec-collaboration.md"
+    "flow2spec-collaboration": ".Knowledge/topics/flow2spec-collaboration.md",
+    "flow2spec-doctor": ".Knowledge/topics/flow2spec-doctor.md"
   },
   "taskToTopicRules": [
     {
@@ -149,6 +150,14 @@
       "topics": [
         "flow2spec-collaboration"
       ]
+    },
+    {
+      "task": "flow2spec-doctor",
+      "matcherId": "m-flow2spec-doctor",
+      "matcherPath": ".Knowledge/matchers/m-flow2spec-doctor.json",
+      "topics": [
+        "flow2spec-doctor"
+      ]
     }
   ],
   "pkgRev": 1,
@@ -221,6 +230,13 @@
       "tags": [
         "policy"
       ]
+    },
+    "flow2spec-doctor": {
+      "primary": "feature",
+      "confidence": "inferred",
+      "tags": [
+        "module"
+      ]
     }
   }
 }

.Knowledge/matchers/m-flow2spec-doctor.json

@@ -0,0 +1,16 @@
+{
+  "includeAny": [
+    "flow2spec doctor",
+    "doctor 命令",
+    "环境诊断",
+    "项目健康检查",
+    "安装检查",
+    "配置检查",
+    "Flow2Spec 诊断",
+    "TASK_ROOT 检查",
+    "知识库健康"
+  ],
+  "id": "m-flow2spec-doctor",
+  "version": "1.0.0",
+  "schema": "flow2spec.matcher.v1"
+}

.Knowledge/stock-docs/Flow2Spec-doctor诊断命令.md

@@ -0,0 +1,42 @@
+# Flow2Spec Doctor 诊断命令
+
+## 定位
+
+`flow2spec doctor` 是面向 Flow2Spec 使用者的只读项目体检入口，用于把分散的环境、初始化、协作和知识库检查汇总成一份可操作报告。首版不提供 `--fix`，不调用网络，也不修改任何项目文件。
+
+## 命令契约
+
+```bash
+flow2spec doctor
+flow2spec doctor --json
+flow2spec doctor --help
+```
+
+- 普通输出逐项显示 `[PASS]`、`[WARN]`、`[FAIL]`，异常项附修复建议。
+- `--json` 输出 `ok`、包信息、当前目录、汇总计数和检查明细，适合脚本或 CI 消费。
+- 警告不阻塞，退出码为 `0`；存在错误时退出码为 `1`。
+- 未知参数直接报错并返回 `1`。
+
+## 检查范围
+
+1. 当前 Node.js 是否满足 `package.json` 的 `engines.node`。
+2. 项目根 `flow2spec.config.json` 是否存在且可解析。
+3. 根 `AGENTS.md` 与 `.Knowledge/manifest-routing.json` 是否存在。
+4. 已存在的 Agent 配置根是否完整：Codex 检查 `.codex/AGENTS.md`、`.codex/hooks.json`；Claude 检查 `.claude/settings.json`；Cursor 检查 `.cursor/hooks.json`。项目没有任何 Agent 配置根时只警告。
+5. 复用 `resolveDeveloperContext` 输出实际 `developerId`、解析来源和 `TASK_ROOT`；无身份回退 legacy `.task/` 时警告。
+6. 根 `.gitignore` 是否显式忽略 `.task/`。
+7. 复用 knowledge engine 做严格知识图校验，并检查 topic revision 与 topic frontmatter 到 routing 元数据的漂移。
+
+## 实现边界
+
+- CLI 分发和参数校验位于 `cli.js`，诊断逻辑与文本格式化位于 `lib/doctor.js`。
+- `lib/doctor.js` 允许测试注入 Node 版本、Git 身份与知识库检查，避免测试依赖开发机全局状态。
+- doctor 只读取项目根已存在的文件；修复动作由用户根据建议显式执行。
+- 旧 topic 缺 `revision` 属严格知识库错误，建议执行 `flow2spec kb build --fix-topics` 后再运行 `flow2spec kb check --strict`。
+- 首版不检查 npm registry 或全局旧包 `@double-codeing/flow2spec`，保持诊断快速、离线、确定。
+
+## 文档入口
+
+- 中文：`docs/命令说明.md` 的 `flow2spec doctor` 章节
+- English: `docs/en/commands-reference.md`, `flow2spec doctor`
+

.Knowledge/topics/flow2spec-doctor.md

@@ -0,0 +1,28 @@
+---
+id: flow2spec-doctor
+revision: 0
+summary: "只读检查 Flow2Spec 环境、初始化、协作上下文与知识库健康"
+primary: feature
+confidence: inferred
+tags: [module]
+---
+# Flow2Spec Doctor
+
+## 适用场景
+
+用于回答或维护 `flow2spec doctor`、项目健康检查、环境诊断、初始化完整性、协作上下文和知识库严格校验。
+
+## 已落地能力
+
+- `flow2spec doctor` 输出人读报告；`flow2spec doctor --json` 输出稳定结构。
+- 检查 Node.js、项目配置、Agent 配置根、`developerId` / `TASK_ROOT`、`.task/` 忽略规则与知识图健康。
+- 告警返回 `0`，错误返回 `1`；全程只读、离线，不提供 `--fix`。
+
+## 维护边界
+
+- 命令分发：`cli.js`
+- 诊断实现：`lib/doctor.js`
+- 自动化测试：`scripts/test-doctor.js`
+- 完整事实：`.Knowledge/stock-docs/Flow2Spec-doctor诊断命令.md`
+- 用户文档：`docs/命令说明.md`、`docs/en/commands-reference.md`
+

cli.js

@@ -15,6 +15,7 @@ const {
   normalizeLocale,
 } = require("./lib/flow2specConfig");
 const knowledgeEngine = require("./lib/knowledgeEngine");
+const { runDoctor, formatDoctorReport } = require("./lib/doctor");
 
 const { execFileSync } = require("child_process");
 
@@ -234,6 +235,7 @@ Flow2Spec - 统一知识库工作流（AI 配置入口）  v${pkg.version}
 用法:
   flow2spec init [agent ...] [--reset-knowledge] [--yes] [--locale zh-CN|en-US]    在当前项目初始化：写入 .Knowledge 与所选 agent 入口
   flow2spec config              打印项目根 ${CONFIG_FILENAME} 的解析结果（缺省值合并后）
+  flow2spec doctor [--json]     只读检查运行环境、项目初始化、协作上下文与知识库健康
   flow2spec kb                  知识库协作引擎：status / check / plan / apply / build
   flow2spec version             显示当前 flow2spec 版本
   flow2spec update              更新 flow2spec 到最新版本；更新后提示执行 f2s-kb-upgrade
@@ -325,6 +327,32 @@ if (sub === "config") {
   process.exit(0);
 }
 
+if (sub === "doctor") {
+  const doctorArgs = args.slice(1);
+  if (doctorArgs.includes("--help") || doctorArgs.includes("-h")) {
+    console.log(`
+用法:
+  flow2spec doctor [--json]
+
+只读检查 Node.js、项目配置、Agent 初始化、协作上下文、.task 忽略规则与知识库健康。
+警告不阻塞（exit 0），错误会返回 exit 1；本命令不会修改文件或访问网络。
+`.trim());
+    process.exit(0);
+  }
+  const unknown = doctorArgs.filter((arg) => arg !== "--json");
+  if (unknown.length > 0) {
+    console.error(`doctor 不支持参数：${unknown.join(" ")}`);
+    process.exit(1);
+  }
+  const report = runDoctor(process.cwd());
+  if (doctorArgs.includes("--json")) {
+    printJson(report);
+  } else {
+    console.log(formatDoctorReport(report));
+  }
+  process.exit(report.ok ? 0 : 1);
+}
+
 if (sub === "kb") {
   const kbSub = args[1];
   const kbFlags = new Set(args.slice(2).filter((arg) => String(arg || "").startsWith("--")));

docs/en/commands-reference.md

@@ -24,7 +24,7 @@
 | `/f2s-kb-migrate` | One-time migration of a legacy knowledge base to `.Knowledge/` | KB Maintenance |
 | `/f2s-kb-upgrade` | Upgrade knowledge base template, align manifest + matchers shards | KB Maintenance |
 
-The table above lists conversation-triggered `/f2s-*` skills. The repository also provides shell commands under `flow2spec kb status / check / plan / apply / build`; they merge a skill-produced `kb-delta.json` into the shared `.Knowledge/`. See [§ 7](#7-flow2spec-kb-cli-for-collaborative-merges).
+The table above lists conversation-triggered `/f2s-*` skills. The repository also provides shell commands: `flow2spec kb status / check / plan / apply / build` handles collaborative knowledge merges (see [§ 7](#7-flow2spec-kb-cli-for-collaborative-merges)), while `flow2spec doctor` performs a read-only project health check (see [§ 8](#8-flow2spec-doctor-project-health-check)).
 
 ---
 
@@ -725,7 +725,36 @@ See [Team Collaboration](./team-collaboration.md) for the operating model and [A
 
 ---
 
-## 8) Quick Reference
+## 8) `flow2spec doctor` (Project Health Check)
+
+`flow2spec doctor` provides one command for diagnosing why Flow2Spec is not behaving as expected. It is read-only, does not access the network, and never modifies project configuration or knowledge files.
+
+```bash
+flow2spec doctor
+flow2spec doctor --json
+```
+
+It checks:
+
+- whether Node.js satisfies the package's `engines.node` requirement
+- whether `flow2spec.config.json`, root `AGENTS.md`, and `.Knowledge/manifest-routing.json` exist and are usable
+- whether detected `.codex`, `.claude`, and `.cursor` roots contain their required entry and hook files
+- the resolved `developerId`, source, and `TASK_ROOT`; falling back to the legacy `.task/` root produces a warning
+- whether the root `.gitignore` ignores `.task/`
+- strict knowledge graph health, topic revisions, and routing metadata drift
+
+Human-readable output marks each check with `[PASS]`, `[WARN]`, or `[FAIL]` and includes a repair suggestion when applicable. `--json` returns a stable `ok / package / cwd / summary / checks` structure for CI and scripts.
+
+Warnings alone return exit code `0`; any error returns `1`. Unknown flags such as `--fix` fail immediately. To repair legacy topics without a `revision`, follow the reported commands:
+
+```bash
+flow2spec kb build --fix-topics
+flow2spec kb check --strict
+```
+
+---
+
+## 9) Quick Reference
 
 For typical work scenarios and full workflows, see [Usage Guide § 3. Typical Workflows](./usage-guide.md).
 

docs/命令说明.md

@@ -24,7 +24,7 @@
 | `/f2s-kb-migrate` | 旧版知识库一次性迁移到 `.Knowledge/` | 知识库维护 |
 | `/f2s-kb-upgrade` | 知识库模板升级，对齐 manifest + matchers 分片 | 知识库维护 |
 
-上表是聊天里触发的 `/f2s-*` 技能。仓库还带一组 **shell CLI**：`flow2spec kb status / check / plan / apply / build`，用来把技能写好的 `kb-delta.json` 合入共享的 `.Knowledge/`，见 [§ 7) `flow2spec kb` CLI](#7-flow2spec-kb-cli协作合库)。
+上表是聊天里触发的 `/f2s-*` 技能。仓库还带 shell CLI：`flow2spec kb status / check / plan / apply / build` 用于协作合库，见 [§ 7](#7-flow2spec-kb-cli协作合库)；`flow2spec doctor` 用于只读项目体检，见 [§ 8](#8-flow2spec-doctor项目体检)。
 
 ---
 
@@ -850,7 +850,36 @@
 
 ---
 
-## 8) 快速参考
+## 8) `flow2spec doctor`（项目体检）
+
+`flow2spec doctor` 在排查“为什么 Flow2Spec 没有按预期工作”时，一次检查本机运行环境和当前项目状态。命令只读、不联网，也不会自动修改配置或知识库。
+
+```bash
+flow2spec doctor
+flow2spec doctor --json
+```
+
+检查范围：
+
+- Node.js 版本是否满足包的 `engines.node`
+- `flow2spec.config.json`、根 `AGENTS.md` 与 `.Knowledge/manifest-routing.json` 是否存在且可用
+- 已存在的 `.codex`、`.claude`、`.cursor` 配置根是否包含必要入口和 hooks
+- 实际解析出的 `developerId`、来源与 `TASK_ROOT`；无法识别身份而回退到 `.task/` 时给出警告
+- 根 `.gitignore` 是否忽略 `.task/`
+- 知识图、topic revision 和 routing 元数据是否通过严格校验
+
+文本输出用 `[PASS]`、`[WARN]`、`[FAIL]` 标记每项，并在异常项后给出修复建议。`--json` 输出稳定的 `ok / package / cwd / summary / checks` 结构，便于 CI 或脚本消费。
+
+退出码规则：仅有警告时返回 `0`；任何错误返回 `1`。`--fix` 等未知参数会直接失败。需要修复旧 topic 缺少 `revision` 时，根据提示运行：
+
+```bash
+flow2spec kb build --fix-topics
+flow2spec kb check --strict
+```
+
+---
+
+## 9) 快速参考
 
 典型工作场景与完整链路见 [使用说明 § 三、典型工作场景](./使用说明.md)。