# [MGMT-STD-005] Khyos 工作方法论：证据搜集 → 做计划 → 计划正确落地（流程铁律）

| 项 | 值 |
| --- | --- |
| 文档类型 | 工程治理标准 / AI 工作方法论（STD） |
| 适用范围 | Khyos（及任何驱动 AI）**接手本仓任何非平凡任务**时的通用工作流。凡「改代码 / 加功能 / 修 bug / 发版 / 写文档」都适用 |
| 强制级别 | 铁律（违反红线 = 改错东西 / 造重复 / 不可逆事故 / 假绿交付） |
| 触发关键词 | 搜集证据 / 做计划 / 落地 / 方法论 / 怎么干 / 从哪下手 |
| 上位 / 参考 | [MGMT-STD-001]（文档结构铁律）；[MGMT-STD-004]（曼孚交付方法论·下游客户交付专用）；活源真相 = 本仓 `scripts/check-*.js` 四守卫 + `services/backend/src/services/planModeService.js` + `services/backend/src/services/docsFreshness/` |
| 状态 | 定稿 |

---

## 0. 用途与一句话定位

**一句话定位**：这是 Khyos 的**通用工作方法论**——先**搜集证据**（跑真解析器 / 读真源，不凭记忆），再**做计划**（分层、门控、可回退、先对齐后动手），最后**正确落地**（守卫验证、诚实报告、不可逆动作先取证再确认）。

[MGMT-STD-004] 管「怎么给曼孚客户交付」，本文管「Khyos 自己怎么把任何一件工程活干对」。两者互补不互抄。

用词纪律（沿用 [MGMT-STD-001]）：红线只用「必须 / 严禁 / 强制」，严禁「建议 / 最好 / 尽量」。

> 本方法论的每一条都**锚定本仓真实机制**，不讲空道理。每节末尾的「活源锚点」指向可核实的代码/脚本——那是这条铁律的证据，也是学习入口。

---

## 1. 心智模型（先建立认知，再谈流程）

三段闭环，缺一不可：

```
  ┌─────────────┐     ┌─────────────┐     ┌─────────────┐
  │ ① 搜集证据   │ ──▶ │ ② 做计划     │ ──▶ │ ③ 正确落地   │
  │ 跑解析器/读源 │     │ 分层·门控·  │     │ 守卫·诚实·   │
  │ 不凭记忆     │     │ 可回退·对齐  │     │ 不可逆先确认 │
  └─────────────┘     └─────────────┘     └─────────────┘
         ▲                                        │
         └────────────── 落地后验证反哺证据 ◀──────┘
```

三条认知红线：

1. **证据 > 记忆 > 猜测**。判「X 存在吗 / X 是什么」必须跑真解析路径或读真源，**严禁**按名硬比、凭训练记忆、凭等价表分类。分类既造假阴（「已覆盖」实则无）又造假阳（「缺」实则有）。
2. **计划先对齐，再动手**。非平凡任务先 EnterPlanMode 探索 + 出计划 + 用户批准，再写代码。计划里就把「门控 / 可回退 / 红线」定死。
3. **落地要验证 + 诚实**。跑守卫、跑测试、跑端到端；测试失败就说失败并附输出；不可逆/对外动作先取证（dry-run）再经用户确认。

---

## 2. 十条工作红线（触碰任一即可能干错事）

1. **严禁凭记忆断言「有没有 / 是什么」**——跑真解析器或读真源。（活源锚点：判 CC 工具是否在 khy 有，要跑 `claudeCompat.normalizeToolName` 真解析路径，不查等价表。）
2. **严禁在成熟体系里造重复**——先诊断该主题归宿（已覆盖→补链接；真缺口→才新建）。用户原词全仓 grep 无命中 = 真小缺口的信号。
3. **严禁手动维护本可派生的映射**——能从既有约定派生就派生（零维护面）。（活源锚点：`docsFreshness/docPathIndex.js` 靠解析正文既有约定派生 source→doc，不写映射表。）
4. **严禁无门控地改既有行为**——新能力挂 `KHY_*` 门控，默认值明确，关闭 = 逐字节回退今日行为。
5. **严禁不可逆/对外动作直接真跑**——先 dry-run 取证，再经用户确认。（活源锚点：`publish-dual.sh --dry-run` 演练全流程不上传；发版是不可逆公开动作。）
6. **严禁落地后不验证就报完成**——三守卫 `--changed` + 测试 + 端到端，缺一不可。（活源锚点：`scripts/check-{leaf-contract,model-hardcoding,agent-rules,change-safety}.js`。）
7. **严禁把「分类了」当「穷尽了」**——不美观/覆盖类扫描要跑到穷尽（逐条命中裁定），不是找几个候选。
8. **严禁碰不属于本任务的东西**——合并冲突文件、别人的产物、gitignored 镜像树，红线 by construction 隔离。
9. **严禁假绿**——测试失败/步骤跳过/部分完成，如实说；「跑了但没交付」要静默截断兜底。
10. **严禁未经要求就 commit/push/发布**——这些是对外/难回退动作，默认只做到「可交付」，动作等用户明确要求。

---

## 3. 第一段——怎么搜集证据（Evidence）

**目标**：在动手前，把「现状真相」摸清到可以下判断的程度。凭的是**跑出来的事实**，不是记忆。

### 3.1 搜集手法（按可靠性从高到低）

1. **跑真解析器**（最可靠）：要判某命令/工具/路径是否存在、解析成什么，直接调它的真解析函数看结果。例：`parseInput('/docs check')` 返回 `{command:'docs',subCommand:'check'}` 才算「命令存在且路由对」。
2. **读真源脚本**：写 how-to 或判行为，读那个脚本照实写，不照记忆写。例：写 PDF 生成文档前读 `scripts/docs/md-to-pdf.js`，确认它「零依赖复用 vendored markdown-it + 系统 chrome」。
3. **跑 grep/find 穷尽扫**：判「某特性被谁消费 / 某原词是否出现」——`grep -rn` 逐条命中，不抽样。
4. **端到端探针**：造隔离环境（tmp 目录 / fake HOME）真跑一遍，看真实输出。
5. **查外部权威端点**：判线上状态查真端点，不查会缓存滞后的聚合接口。例：确认 PyPI 是否已发某版本，查版本专属端点 `pypi.org/pypi/khy-os/0.1.148/json`，不信滞后的 `/khy-os/json` 聚合。

### 3.2 证据搜集的三条铁律

- **跑真解析路径，不按名硬比**。第一次探针若漏了预处理步骤（如 `normalizeToolName` 前置），会误报——要摸到**完整**解析链。
- **重取权威清单**。记忆里的旧审计可能比真源旧（例：真 zip 39 个工具 ≠ 旧审计记的 29）。有权威源就重取。
- **诚实排除要读源实证**。判「这条不算缺口」要读源给证据（是 stub？是云特有？是内部 IPC？），不凭断言。

**活源锚点**：`services/backend/src/services/claudeCompat.js`（`normalizeToolName` + `TOOL_ALIASES` 冻结 SSOT）；本会话文档新鲜度系统的 `docPathIndex.extractSourcePaths` 派生映射即「解析既有约定 = 证据」的范式。

---

## 4. 第二段——怎么做计划（Plan）

**目标**：把摸清的现状，变成一份**分层、可回退、先对齐**的执行计划。计划本身就是防止「改错东西」的护栏。

### 4.1 先对齐，用 EnterPlanMode

非平凡任务（新功能 / 多文件改动 / 多种可行方案 / 需求不清）**必须**先进 plan mode：探索代码 → 出计划 → 需求不清用 AskUserQuestion 澄清 → ExitPlanMode 请用户批准 → 才动手。Khyos 内置 `planModeService` 就是把这条工作流固化成机制。

**活源锚点**：`services/backend/src/services/planModeService.js` / `planModeSink.js`。

### 4.2 计划必须回答的五个问题

一份合格计划里必须写死：

1. **复用还是新建**？先列「已核实的现成基建」，能复用绝不新建（例：镜像 `precommitCheck._gitSoft`，不另写 git 包装）。
2. **命名避碰了吗**？新命令/函数名先 grep，撞了就换（例：`maintain freshness` 已占 → 用 `docs check`）。
3. **门控叫什么、默认什么**？每个新能力一个 `KHY_*`，默认值明确，关 = 字节回退。
4. **怎么回退 / 红线在哪**？合并冲突文件不碰、只改有 bug 那侧、只 `git add` 自己产物——红线尽量 by construction（结构上不可能违反），而非靠记得。
5. **怎么验证**？计划末尾就列出验证清单（守卫 + 测试 + 端到端 + 回归）。

### 4.3 分层纪律（本仓范式）

- **纯叶子 + 门控 + node:test**：纯逻辑落 `services/.../<x>.js`（零 IO、确定性、never-throw、`<x>Enabled(env)` 门控），配 `tests/services/<x>.test.js`。
- **薄 IO 壳**：IO/编排落单独的 runner/service，镜像已有壳（如 `precommitCheck`），fail-soft。
- **叶子绝不 import 需模型/网络的层**——保确定性路径（pre-commit/CI）离线可跑。

**活源锚点**：`scripts/check-leaf-contract.js` + `scripts/lib/leafContractGuard.js` 就是这条分层纪律的自动守卫；`docsFreshness/` 四叶子 + `docsFreshnessRunner.js` 薄壳是范例。

---

## 5. 第三段——怎么让计划正确落地（Land）

**目标**：把计划变成**验证过、诚实、可交付**的改动。落地不是「写完代码」，是「写完 + 验证 + 如实报告」。

### 5.1 落地即验证（缺一不可）

1. **三/四守卫 `--changed`**：`check-leaf-contract` / `check-model-hardcoding` / `check-agent-rules` / `check-change-safety`。0 error 才算过；预存 WARN 要指明「与本改动无关」。
2. **`node --check` 新/改文件**：语法门。
3. **单元测试**：新叶子的 node:test 全绿。
4. **端到端探针**：隔离环境真跑，覆盖「门控开 / 门控关字节回退 / 边界 / 退出码」四态。
5. **回归**：跑相邻既有测试套，证明没打破别的。

### 5.2 不可逆 / 对外动作：先取证，再确认

- **先 dry-run**：发版、删除、覆盖类动作，先跑演练模式看审计是否过、看会动什么。（活源锚点：`publish-dual.sh --dry-run` 走完构建+纯度审计+`twine check` 但不上传。）
- **再经用户确认**：dry-run 干净 ≠ 自动真跑。真上传/真删除**必须**等用户明确要。一处授权不延伸到下一处。
- **落地后查真端点验证**：发布后查版本专属端点确认线上生效，别信滞后的聚合接口。

### 5.3 诚实报告

- 测试失败 → 说失败 + 附输出，绝不粉饰。
- 步骤跳过 → 说跳过。
- 部分完成 → 说部分，别报「全部完成」。
- 「环境已干净」要诚实（数据清了但包还在，就别谎称全净）。
- 改动前若发现现状与描述矛盾（不是你建的 / 内容与描述不符），**先如实反映**，不闷头执行。

### 5.4 落地后反哺

正确落地会产出**新的可复用知识**：写进项目记忆（一事一文件 + `MEMORY.md` 一行索引），链接相关记忆 `[[name]]`。这让下一次的「证据搜集」起点更高。

---

## 6. 全程 SOP（一次任务的标准动作序列）

```
接到任务
  │
  ├─ ① 搜集证据
  │    ├─ 跑真解析器 / 读真源（不凭记忆）
  │    ├─ grep 原词 + 穷尽扫（判缺口 / 判归宿）
  │    └─ 诊断：已覆盖→补链接？真缺口→新建？
  │
  ├─ ② 做计划（非平凡任务 EnterPlanMode）
  │    ├─ 列复用基建 · 命名避碰 grep
  │    ├─ 定门控名+默认 · 定红线（尽量 by construction）
  │    ├─ 分层（纯叶子+门控+test / 薄壳）
  │    ├─ 需求不清 → AskUserQuestion
  │    └─ ExitPlanMode → 用户批准
  │
  ├─ ③ 落地
  │    ├─ 实现（match 周边代码风格）
  │    ├─ 守卫 --changed + node --check + 单测 + 端到端 + 回归
  │    ├─ 不可逆/对外动作：dry-run 取证 → 用户确认 → 真跑 → 查端点验证
  │    └─ 诚实报告（失败/跳过/部分 如实说）
  │
  └─ ④ 反哺：写项目记忆 + MEMORY.md 索引
```

---

## 7. 三个本会话的真实范例（证据 → 计划 → 落地）

这套方法论不是空谈——本会话三件事全按它走：

| 任务 | ① 证据 | ② 计划 | ③ 落地 |
| --- | --- | --- | --- |
| **文档新鲜度系统** | grep 证实 200+ 文档已一致引用源码路径（无需手写映射）；`maintain freshness` 已占 | 四层能力 × 三触发经 AskUserQuestion 定；EnterPlanMode 出计划批准；纯叶子+门控+薄壳 | 68/68 测 + 三守卫净 + E2E 真仓 48 改动→55 suspect + 门控关字节回退 |
| **pip 发版 0.1.148** | 查 PyPI 端点确认线上是 0.1.147、0.1.148 未发；`git status` 摸清未提交改动规模 | AskUserQuestion 定「就发 0.1.148 不含未提交 + 仅 pip 先 dry-run」 | dry-run 审计全绿 → 用户确认 → 真上传 → 查版本专属端点确认 0.1.148 生效 |
| **本方法论文档** | 读 `.ai/` 判 GUARDS 是机器生成不可手改；grep 证实 MGMT-STD-004 是交付专用非通用工作流；锚点全部核实存在 | 定为新 `[MGMT-STD-005]`，每条锚定真实机制 | 守卫核对 + 索引登记 + 交叉链接 + 记忆反哺 |

---

## 8. 与活源的关系（本文件不是唯一真源）

本文件是**方法论的成文表达**；真正的执行约束活在代码与守卫里：

- 分层纪律的强制者 = `scripts/check-leaf-contract.js`（叶子契约守卫）。
- 「不散落模型名」的强制者 = `scripts/check-model-hardcoding.js`。
- 「状态文案要有动作/目标/进度」的强制者 = `scripts/check-agent-rules.js`。
- 改动安全的强制者 = `scripts/check-change-safety.js`。
- plan-before-code 的机制层 = `services/backend/src/services/planModeService.js`。
- 「证据派生而非手工维护」的范例 = `services/backend/src/services/docsFreshness/`。

守卫与代码若与本文冲突，**以守卫/代码为准**，并回来修本文。

---

## 跨分类关联指引

- 下游客户交付专用方法论：[MGMT-STD-004]（曼孚 vibecoding）。
- khy 自身 vibe/spec-coding 能力的**量化验收标准**：[MGMT-STD-006]。本文管「怎么把活干对」，STD-006 管「怎么*量化确认* khy 具备并达成该能力」。
- 文档结构与索引铁律：[MGMT-STD-001]。
- 文档新鲜度机制（本方法论「证据派生」范例的实现）：`docs/07_OPS_运维/` 环境开关与文档规范类 + 活源 `services/backend/src/services/docsFreshness/`。
- 工作流引擎：[OPS-MAN-057] 工作流引擎-khy-workflow。
