svharness 0.14.13 → 0.14.17

package/docs/agent-launcher-design.md

@@ -41,17 +41,16 @@
                             │
 ┌───────────────────────────▼─────────────────────────────────┐
 │ 核心层  src/lib/agent-launcher.ts                            │
-│  resolveWorkdir() → syncEnv() → preflight() → spawn()       │
+│  resolveWorkdir() → syncEnv() → resolveRunner() → spawn()   │
 └───────────────────────────┬─────────────────────────────────┘
                             │
 ┌───────────────────────────▼─────────────────────────────────┐
-│ 平台层                                                       │
-│  win32: ~/.codechat/cli_app/run.bat                          │
-│  linux: ~/.codechat/cli_app/run.sh                           │
+│ Runner 解析  src/lib/codechat-runner-resolver.ts             │
+│  CODECHAT_CLI_RUNNER → standalone → IDE 插件扫描             │
 └───────────────────────────┬─────────────────────────────────┘
                             │
 ┌───────────────────────────▼─────────────────────────────────┐
-│ 外部依赖  CodeChat CLI                                        │
+│ 外部依赖  CodeChat CLI（run.bat / run.sh）                    │
 └─────────────────────────────────────────────────────────────┘
 ```
 
@@ -150,22 +149,95 @@ launch_codechat_cli ./my-app     # 指定 workdir
 
 ---
 
-## 6. 平台差异
+## 6. Runner 解析 `resolveCodechatRunner()`
 
-| 项 | Windows (`win32`) | Linux |
-|----|-------------------|-------|
-| Runner | `~/.codechat/cli_app/run.bat` | `~/.codechat/cli_app/run.sh` |
-| spawn | `shell: true` | `shell: false` |
-| 右键菜单 | 支持 | 不支持 |
-| postinstall | global install 自动 `shell install` | 跳过 |
+实现：`src/lib/codechat-runner-resolver.ts`
 
-macOS (`darwin`) 路径约定与 Linux 相同；若 runner 不存在则报错。
+### 6.1 优先级（高 → 低）
+
+| 优先级 | 来源 | 说明 |
+|--------|------|------|
+| 1 | `CODECHAT_CLI_RUNNER` | 环境变量显式指向 `run.bat` / `run.sh` 绝对路径 |
+| 2 | standalone | `~/.codechat/cli_app/run.bat`（Win）或 `run.sh`（Linux/macOS） |
+| 3 | IDE 插件 | 扫描 Android Studio / IntelliJ IDEA 插件目录 |
+
+启动日志示例：
+
+```text
+CodeChat CLI: C:\Users\...\AndroidStudio2024.2\plugins\CodeChat\cli\run.bat (ide-plugin: Android Studio 2024.2)
+启动 CodeChat Agent（workdir: D:\projects\my-app）
+```
+
+### 6.2 IDE 插件扫描路径
+
+不绑定具体 IDE 版本号，遍历版本化安装目录（如 `AndroidStudio2024.2`）。
+
+| 平台 | 扫描根目录 | 目录前缀 |
+|------|------------|----------|
+| Windows | `%APPDATA%\Google\` | `AndroidStudio*` |
+| Windows | `%APPDATA%\JetBrains\` | `IntelliJIdea*`、`IdeaIC*` |
+| Linux | `~/.local/share/JetBrains/` | `IntelliJIdea*`、`IdeaIC*` |
+| macOS | `~/Library/Application Support/Google/` | `AndroidStudio*` |
+| macOS | `~/Library/Application Support/JetBrains/` | `IntelliJIdea*`、`IdeaIC*` |
+
+完整 runner 路径模式：
+
+```text
+<root>/<Prefix><version>/plugins/CodeChat/cli/run.bat   # Windows
+<root>/<Prefix><version>/plugins/CodeChat/cli/run.sh    # Linux/macOS
+```
+
+### 6.3 多候选选择规则
+
+Android Studio 与 IntelliJ IDEA 同时安装 CodeChat 插件时：
+
+1. 从目录名解析版本号（`AndroidStudio2024.2` → `[2024, 2]`），**版本最高者优先**
+2. 版本相同则比较 runner 文件 `mtime`，取最新
+3. `label` 写入日志（如 `Android Studio 2024.2`）
+
+### 6.4 返回结构
+
+```typescript
+interface ResolvedCodechatRunner {
+  runner: string;           // 绝对路径
+  source: 'env' | 'standalone' | 'ide-plugin';
+  label?: string;           // 如 "Android Studio 2024.2"
+}
+```
+
+### 6.5 不变约束
+
+- **`--env-file` 仍固定为 `~/.claude/.env`**（见 §5 env 同步策略）；IDE 插件版 `run.bat` 与用户手动调用参数兼容（`--env-file` + `--cwd`）
+- 右键 stub / `launch_codechat_cli` 间接受益，**无需**改 registry
+
+### 6.6 示例
+
+```powershell
+# 自动解析（standalone 不存在，仅 IDE 插件）
+# → C:\Users\<user>\AppData\Roaming\Google\AndroidStudio2024.2\plugins\CodeChat\cli\run.bat
+svharness start-agent --work-dir D:\projects\my-app
+
+# 显式覆盖
+$env:CODECHAT_CLI_RUNNER = "$env:APPDATA\Google\AndroidStudio2024.2\plugins\CodeChat\cli\run.bat"
+svharness start-agent --work-dir D:\projects\my-app
+```
 
 ---
 
-## 7. Windows 右键集成
+## 7. 平台差异
+
+| 项 | Windows (`win32`) | Linux | macOS (`darwin`) |
+|----|-------------------|-------|------------------|
+| Runner | 见 §6 Runner 解析；默认 standalone，缺失时 IDE 插件回退 | 同左 | 同左 |
+| spawn | `shell: true` | `shell: false` | `shell: false` |
+| 右键菜单 | 支持 | 不支持 | 不支持 |
+| postinstall | global install 自动 `shell install` | 跳过 | 跳过 |
 
-### 7.1 为何需要 stub
+---
+
+## 8. Windows 右键集成
+
+### 8.1 为何需要 stub
 
 资源管理器触发的命令 **不保证** 含 `%AppData%\npm` PATH。因此 registry 指向固定路径：
 
@@ -175,7 +247,7 @@ macOS (`darwin`) 路径约定与 Linux 相同；若 runner 不存在则报错。
 
 stub 接收 Explorer 传入的目录参数，`cd` 后调用 **绝对路径** 的 `bin/launch-codechat-cli.js`。
 
-### 7.3 终端与编码（右键 vs 手动 PowerShell）
+### 8.3 终端与编码（右键 vs 手动 PowerShell）
 
 | 启动方式 | 典型终端 | 现象 |
 |----------|----------|------|
@@ -191,7 +263,7 @@ stub 接收 Explorer 传入的目录参数，`cd` 后调用 **绝对路径** 的
 
 重新注册：`svharness shell install`
 
-### 7.4 注册表结构
+### 8.4 注册表结构
 
 | 位置 | 键 |
 |------|-----|
@@ -200,6 +272,14 @@ stub 接收 Explorer 传入的目录参数，`cd` 后调用 **绝对路径** 的
 
 菜单标题：`在此启动 CodeChat CLI`
 
+Icon（两处菜单键均设置）：
+
+```text
+C:\Users\<user>\AppData\Local\svharness\bin\codechat-agent.ico,0
+```
+
+源文件：`assets/codechat-agent.ico`（圆角边框 + `>_` 终端提示符；可用 `scripts/generate-shell-icon.ps1` 重新生成）。
+
 Command（Background，已安装 WT 时）：
 
 ```text
@@ -230,7 +310,7 @@ stub 脚本须为 **UTF-8 BOM + ASCII 正文**（Windows PowerShell 5.1 对无 B
 
 ---
 
-## 8. 生命周期钩子
+## 9. 生命周期钩子
 
 ### postinstall
 
@@ -246,11 +326,12 @@ stub 脚本须为 **UTF-8 BOM + ASCII 正文**（Windows PowerShell 5.1 对无 B
 
 ---
 
-## 9. 错误与用户提示
+## 10. 错误与用户提示
 
 | 场景 | 消息要点 |
 |------|----------|
-| runner 缺失 | 平台对应 `run.bat` / `run.sh` 路径 |
+| runner 缺失 | 列出三级尝试路径（env / standalone / IDE 扫描根目录）；提示设置 `CODECHAT_CLI_RUNNER` |
+| `CODECHAT_CLI_RUNNER` 不可访问 | 环境变量路径 + 「不可访问」 |
 | workdir 不存在 | 绝对路径 + 「工作目录不存在」 |
 | workdir 冲突 | `--work-dir` 与位置参数不一致 |
 | env 缺失 | 项目级或用户级 `.claude/.env` 创建指引 |
@@ -259,7 +340,7 @@ stub 脚本须为 **UTF-8 BOM + ASCII 正文**（Windows PowerShell 5.1 对无 B
 
 ---
 
-## 10. 安全说明
+## 11. 安全说明
 
 默认向 CodeChat CLI 传递 **`--dangerously-skip-permissions`**，以便 harness 构建流程（S10–S90）在自动化场景下少打断。
 
@@ -271,18 +352,19 @@ svharness start-agent --work-dir . --no-skip-permissions
 
 ---
 
-## 11. 扩展点
+## 12. 扩展点
 
 | 扩展 | 状态 |
 |------|------|
 | `start-agent cursor` / `claude-code` | 预留 agent 配置表 |
-| `CODECHAT_CLI_RUNNER` 环境变量 | 未实现 |
+| `CODECHAT_CLI_RUNNER` 环境变量 | **已实现**（最高优先级 override） |
+| CLI flag `--runner` | 未实现（环境变量足够；后续可按需扩展） |
 | `svharness.config.yaml` → `startAgent` 节 | 未实现 |
 | Linux 文件管理器 actions (Nautilus) | 未实现 |
 
 ---
 
-## 12. 故障排查 FAQ
+## 13. 故障排查 FAQ
 
 **Q: `launch_codechat_cli` 不是内部或外部命令**
 
@@ -296,7 +378,14 @@ svharness start-agent --work-dir . --no-skip-permissions
 
 **Q: 未找到 run.bat / run.sh**
 
-安装 CodeChat CLI 到 `~/.codechat/cli_app/`。
+1. **独立安装**：CodeChat CLI 到 `~/.codechat/cli_app/`
+2. **IDE 插件**：在 Android Studio 或 IntelliJ IDEA 中安装 CodeChat 插件（无需指定版本号，`start-agent` 会自动扫描 `%APPDATA%\Google\AndroidStudio*` 等路径）
+3. **手动指定**：
+
+```powershell
+$env:CODECHAT_CLI_RUNNER = "$env:APPDATA\Google\AndroidStudio2024.2\plugins\CodeChat\cli\run.bat"
+svharness start-agent --work-dir D:\projects\my-app
+```
 
 **Q: env 文件缺失**
 
@@ -314,13 +403,25 @@ SVHARNESS_SKIP_SHELL=1 npm install -g svharness
 
 ---
 
-## 13. 源码索引
+## 14. 源码索引
 
 | 模块 | 路径 |
 |------|------|
 | 启动核心 | `src/lib/agent-launcher.ts` |
+| Runner 解析 | `src/lib/codechat-runner-resolver.ts` |
 | start-agent 命令 | `src/commands/start-agent.ts` |
 | 右键集成 | `src/commands/shell-integration.ts` |
 | 注册表工具 | `src/lib/win-registry.ts` |
 | 全局 bin | `bin/launch-codechat-cli.js` |
 | postinstall | `scripts/postinstall.js` |
+
+---
+
+## 15. 独立 PowerShell 启动器（附录）
+
+无需 Node / svharness 时，可分发 [`templates/codechat/Start-CodeChat.ps1`](../templates/codechat/Start-CodeChat.ps1)：
+
+- env / runner 行为与 §5、§6 对齐（PowerShell 自实现）
+- 右键注册表键 **`CodeChatStandaloneAgent`**，与 §8 svharness 键 **`SvharnessLaunchCodeChatAgent`** 隔离，可并存
+
+完整用法见 [`standalone-codechat-ps1.md`](standalone-codechat-ps1.md)。

package/docs/standalone-codechat-ps1.md

@@ -0,0 +1,123 @@
+# 独立 CodeChat PowerShell 启动器
+
+> 无需安装 Node.js / svharness，拷贝脚本即可启动 CodeChat CLI。
+
+脚本路径：[`templates/codechat/Start-CodeChat.ps1`](../templates/codechat/Start-CodeChat.ps1)
+
+## 适用场景
+
+- 团队未使用 svharness，但项目根已有 `.claude/.env`
+- CodeChat 仅通过 **Android Studio / IntelliJ IDEA 插件**安装（无 `~/.codechat/cli_app/run.bat`）
+- 希望在资源管理器右键启动，且**不与** `svharness shell install` 的全局菜单冲突
+
+## 快速开始
+
+```powershell
+# 1. 拷贝到项目（推荐 .claude\）
+Copy-Item .\templates\codechat\Start-CodeChat.ps1 .\.claude\
+
+# 2. 在项目根启动
+cd D:\projects\my-app
+.\.claude\Start-CodeChat.ps1
+
+# 3. 可选：注册 Explorer 右键（独立菜单项）
+.\.claude\Start-CodeChat.ps1 -Action InstallMenu
+
+# 4. 状态 / 卸载右键
+.\.claude\Start-CodeChat.ps1 -Action Status
+.\.claude\Start-CodeChat.ps1 -Action UninstallMenu
+```
+
+## 子命令 `-Action`
+
+| Action | 说明 |
+|--------|------|
+| `Start`（默认） | 同步 env → 解析 `run.bat` → 启动 CodeChat |
+| `InstallMenu` | 复制脚本到 `%LOCALAPPDATA%\codechat-standalone\` 并注册 HKCU 右键 |
+| `UninstallMenu` | 删除独立注册表键与 `%LOCALAPPDATA%\codechat-standalone\` |
+| `Status` | 打印 runner / env / 菜单注册状态 |
+
+## Start 参数
+
+| 参数 | 说明 |
+|------|------|
+| `-WorkDir` | 项目根目录，默认当前目录 |
+| `-NoSyncEnv` | 不同步项目 `.claude/.env`（仅使用已有 `~/.claude/.env`） |
+| `-NoSkipPermissions` | 不传 `--dangerously-skip-permissions` |
+
+## env 策略（与 svharness 一致）
+
+| 步骤 | 行为 |
+|------|------|
+| 项目有 `.claude/.env` 且未 `-NoSyncEnv` | **只读**项目文件，复制到 `~/.claude/.env`（覆盖用户 env） |
+| 项目无 env，用户 env 存在 | 使用 `~/.claude/.env` |
+| 均无 | 报错，提示创建项目 `.claude/.env` |
+
+启动时 `--env-file` 始终指向 **`~/.claude/.env`**，不修改项目内 env 文件。
+
+## Runner 解析优先级
+
+| 优先级 | 来源 |
+|--------|------|
+| 1 | 环境变量 `CODECHAT_CLI_RUNNER` |
+| 2 | `~/.codechat/cli_app/run.bat` |
+| 3 | IDE 插件扫描（版本最高 + 文件最新）： |
+| | `%APPDATA%\Google\AndroidStudio*\plugins\CodeChat\cli\run.bat` |
+| | `%APPDATA%\JetBrains\IntelliJIdea*\plugins\CodeChat\cli\run.bat` |
+| | `%APPDATA%\JetBrains\IdeaIC*\plugins\CodeChat\cli\run.bat` |
+
+手动指定 runner：
+
+```powershell
+$env:CODECHAT_CLI_RUNNER = "$env:APPDATA\Google\AndroidStudio2024.2\plugins\CodeChat\cli\run.bat"
+.\.claude\Start-CodeChat.ps1
+```
+
+## 与 svharness 对比
+
+| 项 | `svharness start-agent` | `Start-CodeChat.ps1` |
+|----|-------------------------|----------------------|
+| 依赖 | Node.js + npm 全局包 | 仅 PowerShell |
+| env 同步 | 项目 → `~/.claude/.env` | 相同 |
+| runner 扫描 | `codechat-runner-resolver.ts` | PS1 内等价逻辑 |
+| 右键注册表键 | `SvharnessLaunchCodeChatAgent` | `CodeChatStandaloneAgent` |
+| 菜单标题 | 在此启动 CodeChat CLI | 在此启动 CodeChat（项目 env） |
+| stub 目录 | `%LOCALAPPDATA%\svharness\bin\` | `%LOCALAPPDATA%\codechat-standalone\` |
+
+两者**可同时安装**：Explorer 中会出现两条菜单（若都注册了右键）。
+
+卸载独立菜单 **不会** 影响 `svharness shell` 注册的菜单。
+
+## 右键安装细节
+
+- 脚本复制到：`%LOCALAPPDATA%\codechat-standalone\Start-CodeChat.ps1`
+- 若同目录或上级存在 `codechat-agent.ico` / `assets/codechat-agent.ico`，会一并复制为菜单图标
+- 已安装 Windows Terminal 时，注册表直接调用 `wt.exe`（单窗口，与 svharness 右键行为一致）
+
+## 故障排查
+
+**ExecutionPolicy 阻止脚本**
+
+```powershell
+powershell -ExecutionPolicy Bypass -File .\.claude\Start-CodeChat.ps1
+```
+
+**找不到 run.bat**
+
+- 确认 Android Studio / IDEA 已安装 CodeChat 插件
+- 或设置 `CODECHAT_CLI_RUNNER` 指向插件内 `run.bat`
+
+**No env file**
+
+- 在项目根创建 `.claude\.env`
+
+**与 svharness 菜单混淆**
+
+- 独立菜单标题含「项目 env」
+- `Start-CodeChat.ps1 -Action Status` 仅报告 `CodeChatStandaloneAgent` 状态
+- `svharness shell status` 报告 svharness 菜单状态
+
+## 相关文档
+
+- Agent Launcher 详细设计：[`agent-launcher-design.md`](agent-launcher-design.md)
+- svharness CLI：[`README.md`](../README.md) 中 `start-agent` 章节

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "svharness",
-  "version": "0.14.13",
+  "version": "0.14.17",
   "description": "CLI scaffolder for SDD-Driven Agent-Agnostic Coding Framework (harness)",
   "bin": {
     "svharness": "./bin/cli.js",
@@ -11,6 +11,7 @@
     "dist/",
     "bin/",
     "docs/",
+    "assets/",
     "scripts/postinstall.js",
     "scripts/preuninstall.js",
     "templates/",

package/scripts/preuninstall.js

@@ -7,11 +7,51 @@ if (process.env.npm_config_global !== 'true') {
   process.exit(0);
 }
 
-(async () => {
+/**
+ * IMPORTANT:
+ * - Keep this script synchronous and self-contained.
+ * - Do NOT require compiled JS from dist/, because npm uninstall may remove files
+ *   before this hook finishes (best-effort but should be robust).
+ */
+
+const { execFileSync } = require('child_process');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const REG = 'reg.exe';
+const STUB_DIR = path.join(
+  process.env.LOCALAPPDATA || path.join(os.homedir(), 'AppData', 'Local'),
+  'svharness',
+);
+
+function regDeleteKey(key) {
+  try {
+    execFileSync(REG, ['delete', key, '/f'], { stdio: 'ignore', windowsHide: true });
+  } catch {
+    // best effort
+  }
+}
+
+function removeDirRecursive(dir) {
   try {
-    const { runShellUninstall } = require('../dist/commands/shell-integration');
-    await runShellUninstall({ silent: true });
+    if (fs.existsSync(dir)) {
+      fs.rmSync(dir, { recursive: true, force: true });
+    }
   } catch {
-    // best effort on uninstall
+    // best effort
   }
-})();
+}
+
+// Current keys (since 2026-05)
+regDeleteKey(
+  'HKCU\\Software\\Classes\\Directory\\Background\\shell\\SvharnessLaunchCodeChatAgent',
+);
+regDeleteKey('HKCU\\Software\\Classes\\Directory\\shell\\SvharnessLaunchCodeChatAgent');
+
+// Legacy keys (older releases / experiments)
+regDeleteKey('HKCU\\Software\\Classes\\Directory\\Background\\shell\\svharness_codechat');
+regDeleteKey('HKCU\\Software\\Classes\\Directory\\shell\\svharness_codechat');
+
+// Stub files + icon under %LOCALAPPDATA%\svharness
+removeDirRecursive(STUB_DIR);

package/templates/_shared/build-rules/harness-build-rule-agent-agnostic.md

@@ -5,9 +5,9 @@ harness 是 SDD-Driven Agent-Agnostic Coding Framework。spec 层与 task 层产
 ## 绝对禁止
 
 - 在 `specs/**`、`tasks/**`、`agent-env/rules/**`、`agent-env/memory/categories/**` 的内容里出现以下任一：
-  - 具体 agent 名（如 `qoder`、`codechat`、`cursor`、`claude-code`、`opencode`、`claude`、`chatgpt`、`gpt-4` 等）。
+  - 具体 agent 名（如 `qoder`、`codechat`、`cursor`、`claude-code`、`opencode`、`codex`、`claude`、`chatgpt`、`gpt-4` 等）。
   - 某一 agent 的私有指令语法（如特定 slash command、特定 frontmatter 字段）。
-  - 某一 agent 的私有目录路径（`.qoder/`、`.codechat/`、`.cursor/`、`.claude/`、`.opencode/` 等）。
+  - 某一 agent 的私有目录路径（`.qoder/`、`.codechat/`、`.cursor/`、`.claude/`、`.opencode/`、`.agents/` 等）。
 
 ## 允许出现 agent 标识的位置（白名单）
 

package/templates/_shared/build-rules/harness-build-rule-specs-schema.md

@@ -18,7 +18,7 @@ specs/
 
 - 写入任一 `specs/<domain>/*.yaml` 前，必须先读 `specs/<domain>/schema.json`。
 - 字段增减/重命名时，`schema.json` 与对应 yaml 必须**同一提交**更新，不得分两步。
-- yaml 中不得出现任何具体 agent 名（qoder/codechat/cursor/claude-code/opencode 等）— 违反 agent-agnostic 铁律。
+- yaml 中不得出现任何具体 agent 名（qoder/codechat/cursor/claude-code/opencode/codex 等）— 违反 agent-agnostic 铁律。
 
 ## requirements 追溯字段要求（S40/S50 配套）
 

package/templates/_shared/build-skills/harness-build-skill-orchestrator.md

@@ -112,7 +112,7 @@ description: >
 
 执行任何阶段前，先加载并严格遵循以下规则（文件位于当前 agent 的 rules 目录，
 如 `.qoder/rules/`、`.codechat/rules/`、`.cursor/rules/harness-build/`、
-`.claude/rules/`、`.opencode/rules/`、`.harness/rules/`，具体扩展名随 agent 可能为 `.md` 或 `.mdc`）：
+`.claude/rules/`、`.opencode/rules/`、`.agents/rules/`、`.harness/rules/`，具体扩展名随 agent 可能为 `.md` 或 `.mdc`）：
 
 - `harness-build-rule-orchestrator-flow` — 构建阶段准入/退出红线，任何调度决策都必须匹配。
 - `harness-build-rule-convert-check` — S30_convert_docs 阶段须检查 `requirements/raw/` 与 `references/raw/`，确保非 md 原始文档已转为 Markdown 方可推进。

package/templates/_shared/build-skills/harness-build-skill-wiki-writer.md

@@ -1,7 +1,7 @@
 ---
 name: harness-build-skill-wiki-writer
 description: >
-  逐页撰写 baseline wiki 正文。读取 state 中 `tasks_file` 指向的任务清单与 structure.xml，
+  逐页撰写 baseline wiki 正文（面向编码 Agent 的知识页）。读取 state 中 `tasks_file` 指向的任务清单与 structure.xml，
   基于 baseline/code/ 下的源码快照产出每一页 Markdown。当用户说"生成 baseline wiki 正文"、
   "按 TASKS.md 逐页生成 baseline wiki"、"继续写 wiki 下一页"，或由 harness-build-skill-orchestrator
   在阶段 S10_wiki 委派时触发。
@@ -10,7 +10,7 @@ description: >
 # harness-build-skill-wiki-writer（baseline wiki 正文撰写）
 
 你只做一件事：**按 `__HARNESS_ROOT__.harness-build-state.yaml` 中 `S10_wiki.tasks_file` 指向的任务清单，
-一页一页地，基于 `__HARNESS_ROOT__baseline/code/` 下的真实源码，写成 Markdown**。
+一页一页地，基于 `__HARNESS_ROOT__baseline/code/` 下的真实源码，写成面向编码 Agent 的 Markdown 知识页**。
 references intake、agent-env 合并、skills/tasks 索引不是你的职责（分别由 harness-build-skill-references-intake、harness-build-skill-agent-env-merge、harness-build-skill-knowledge-builder 负责）。
 
 ## 输入
@@ -33,17 +33,26 @@ references intake、agent-env 合并、skills/tasks 索引不是你的职责（
 5. 写完后最小补丁式修改 `TASKS.md`，把该任务的 `[ ]` 改为 `[x]`（不得重排任务顺序、不得删除其他行）。
 6. 默认单步询问是否继续下一页。如果用户说"批量"、"全部继续"、"run through"，则连续处理至清单尾。
 
-## 撰写规则（强制，与 --generate-wiki 的产出口径必须一致）
+## 撰写规则（强制，与 build `--generate-wiki` Agent 向产出口径必须一致）
 
 - **H1** 必须与 task `Title` 完全一致。
-- **简介段** 后若后续有 2 个及以上的 `##` 章节，插入锚点式 TOC。
-- **Mermaid** 使用 `graph TD` 或 `sequenceDiagram`，不使用 classDef / style / 颜色。
+- **H1 下方** 立即一行：`Sources: <repo-relative>/path:start-end, ...`
+- **固定章节顺序**（不得省略；空则写「见关键路径」或「暂无」）：
+  1. `## 阅读时机` — 1–3 条 bullet：编码 Agent 何时应读本文
+  2. `## 关键路径` — 表格：用途 | 路径 | 符号/类
+  3. `## 扩展与修改入口` — 如何新增/修改类似功能
+  4. `## 数据流 / 调用链` — 短文字；**仅**在非显然链路时用 `graph TD` 或 `sequenceDiagram`
+  5. `## 约定与禁区` — 必须遵守与禁止事项
+  6. `## 关联` — 相关 wiki 页或模块（若可推断）
+- **禁止** 简介段 + 锚点 TOC（Agent 向页面不使用人类教程式 TOC）。
+- **Mermaid** 可选；不使用 classDef / style / 颜色。
 - **引用源码** 必须指向 `__HARNESS_ROOT__baseline/code/`。允许两种书写方式（可混用）：
   - 行内链接：`[Foo.java:10-30](../../baseline/code/<repo-relative>/Foo.java#L10-L30)`
   - Sources 行：`Sources: <repo-relative>/Foo.java:10-30, <repo-relative>/Bar.kt:5-8`
   `<repo-relative>` 是**相对 `__HARNESS_ROOT__baseline/code/` 的路径**，既不是仓库原始绝对路径，
   也不是 wiki md 文件的相对路径。行号采用 `start-end`（闭区间）。
-- 禁止粘贴大段代码：单个 code block ≤ 40 行；必要时用省略号 `// ...` 裁剪。
+- 禁止粘贴大段代码：单个 code block ≤ 40 行；必要时用省略号 `// ...` 裁剪；优先接口/签名片段。
+- 单段 prose 不超过 5 行（除代码块外）；以表格与 bullet 为主。
 - 所有中文段落使用中文标点；字段名、类名、路径保留英文不译。
 
 ## 产出