svharness 0.8.0 → 0.11.0

package/README.md

@@ -29,6 +29,12 @@ cd svharnessbuild && npm install && npm run build && npm link
 # 最简 —— 只填名字，其余取默认（arch=android-compose, agent=codechat）
 svharness build --harness-name my-app
 
+# 交互式向导（推荐新手）—— 可填路径 + 文字说明，保存配置或立即执行
+svharness wizard
+
+# 配置文件驱动（团队模板 / CI）
+svharness build --config svharness.config.yaml --yes
+
 # 一行式 —— 跳过交互，直接生成
 svharness build --harness-name my-app --arch android-compose --agent qoder --yes
 
@@ -36,10 +42,38 @@ svharness build --harness-name my-app --arch android-compose --agent qoder --yes
 svharness apply --harness ./my-app-harness --target ../other-project --yes
 ```
 
+### 配置文件与向导（v0.10+）
+
+**优先级**：`CLI 参数 > svharness.config.yaml > 代码默认值`
+
+1. 复制示例配置：`templates/svharness.config.example.yaml` → 项目根 `svharness.config.yaml`
+2. 编辑 `build` / `apply` / `convert` 各节参数
+3. 执行：`svharness build --yes`（自动读取当前目录下的 `svharness.config.yaml`）
+
+也可显式指定：`svharness build --config ./team/android-compose.yaml --yes`
+
+`build` 成功后落盘当前参数：`svharness build --harness-name my-app --save-config`
+
+**`svharness wizard`**：分步 TUI，支持同时填写**文件路径**与**说明文字**（如 `requirementsNote`），结束时可选「立即执行 / 仅保存配置 / 保存并执行」。
+
 生成完成后，在你的 Agent IDE 中说：
-- "运行 harness-build-skill-orchestrator"即可开始逐步填充内容；
+- "运行 harness-build-skills-main"或"harness-build-skill-orchestrator"即可开始逐步填充内容；
 - 构建完成后在目标项目中说"应用 harness-apply-skills-main 完成 xxx 功能开发"即可调用 harness。
 
+### 演示数据集（demo_project）
+
+仓库自带 **[`demo_project/`](./demo_project/)**（Python 计算器主题），可一次性验证 `--baseline` / `--requirements` / `--references` / `--extra-skills` 四类输入及 intake 分类。详见 [`demo_project/README.md`](./demo_project/README.md)。
+
+```powershell
+cd svharnessbuild
+svharness build --harness-name demo-py --arch python --agent codechat `
+  --baseline ./demo_project/baseline `
+  --requirements ./demo_project/requirements `
+  --references ./demo_project/references `
+  --extra-skills ./demo_project/extra-skills `
+  --yes --force
+```
+
 ---
 
 ## 核心概念
@@ -51,7 +85,7 @@ Harness 是一个 **项目本地的知识层**，由两大部分组成：
 | 部分 | 位置 | 生命周期 | 说明 |
 |------|------|----------|------|
 | **Agent 注入目录** | `.qoder/` / `.codechat/` / `.cursor/` 等 | `build` 时创建，Agent 自动加载 | rules + build-skills |
-| **Harness 目录** | `<harness-name>-harness/` | `build` 创建骨架 → Agent 逐步填充 | specs / assets / agent-env / tasks |
+| **Harness 目录** | `<harness-name>-harness/` | `build` 创建骨架 → Agent 逐步填充 | specs / requirements / references / baseline / agent-env / tasks |
 
 ### 目录结构
 
@@ -60,11 +94,11 @@ Harness 是一个 **项目本地的知识层**，由两大部分组成：
 ```
 <harness-name>-harness/
 ├── harness.yaml                  # 入口清单（架构 / agent / schema 引用）
-├── AGENTS.md                     # 面向 Agent 的使用指南
+├── AGENTS_BUILD.md                     # 面向 Agent 的使用指南
 ├── README.md                     # 面向人的项目概览
 ├── VERSION
 ├── CHANGELOG.md
-├── .harness-build-state.yaml     # 构建进度追踪（P1 … P-Final）
+├── .harness-build-state.yaml     # 构建进度追踪（S10 … S90）
 │
 ├── specs/                        # 契约层
 │   ├── signals/schema.json
@@ -72,12 +106,17 @@ Harness 是一个 **项目本地的知识层**，由两大部分组成：
 │   ├── behavior/schema.json
 │   └── interfaces/schema.json
 │
-├── assets/                       # 支撑素材（非契约）
-│   ├── raw/                      #   原始需求文档
-│   ├── requirements/             #   条目化后的需求
-│   └── baseline/
-│       ├── code/                 #   参考代码快照
-│       └── wiki/                 #   架构 wiki
+├── requirements/                   # 正式需求（参与条目化）
+│   ├── raw/                        #   S20_collect_inputs 用户入口
+│   ├── md/                         #   convert 产物
+│   └── yaml/                       #   S40 条目化产出
+├── references/                     # 参考资料（不参与条目化）
+│   ├── raw/
+│   ├── md/
+│   └── yaml/
+└── baseline/
+    ├── code/                       #   参考代码快照
+    └── wiki/                       #   架构 wiki
 │
 ├── agent-env/                    # Agent 运行期环境
 │   ├── rules/                    #   编码规则（.mdc，always_on 加载）
@@ -89,15 +128,31 @@ Harness 是一个 **项目本地的知识层**，由两大部分组成：
 └── tasks/                        # 可复用的开发者工作流
 ```
 
-同时，CLI 会向 Agent IDE 的 skill 目录注入 **4 个构建辅助 skill**：
+同时，CLI 会在**项目根**写入 `CLAUDE.md`（`--agent codechat` 或 `claude-code`）或 `AGENTS.md`（`qoder` / `cursor` / `opencode` / `generic`），并向 Agent IDE 的 skill 目录注入 **7 个构建辅助 skill**：
 
 | Skill | 职责 |
 |-------|------|
+| `harness-build-skills-main` | **总清单**：解析内联绑定元数据 → 装载构建规则 → 路由到各子 skill |
 | `harness-build-skill-orchestrator` | 读取构建状态，路由到下一阶段 |
 | `harness-build-skill-spec-builder` | raw → requirements → specs 管线 |
-| `harness-build-skill-knowledge-builder` | baseline 快照 / rules / skills 索引 |
+| `harness-build-skill-references-intake` | S60 references 转换 + 结构化索引 |
+| `harness-build-skill-agent-env-merge` | S61 baseline 自动提取确认 + S65 合并写入 |
+| `harness-build-skill-knowledge-builder` | S10 baseline 样本 + S70 skills/tasks 索引 |
 | `harness-build-skill-wiki-writer` | 按 TASKS.md 逐页撰写 wiki 正文 |
 
+简短阶段对照（阶段 → skill）：
+
+```text
+S10_wiki                -> harness-build-skill-wiki-writer（正文）/ harness-build-skill-knowledge-builder（样本子任务）
+S20_collect_inputs      -> harness-build-skill-orchestrator
+S30_convert_docs        -> harness-build-skill-orchestrator
+S40/S50                 -> harness-build-skill-spec-builder
+S60                     -> harness-build-skill-references-intake
+S61/S65                 -> harness-build-skill-agent-env-merge
+S70                     -> harness-build-skill-knowledge-builder
+S80/S90                 -> harness-build-skill-orchestrator
+```
+
 `.harness-build-state.yaml` 跟踪进度，任何阶段可中断再续。
 
 #### 构建辅助 skill / rule 命名规范
@@ -112,7 +167,7 @@ harness-build-{skill|rule}-<semantic-name>
 
 | 资源类型 | 目录 | 命名模式 | 现有成员 |
 |----------|------|----------|----------|
-| **Build skill** | `templates/_shared/build-skills/` | `harness-build-skill-<name>.md` | `orchestrator` / `spec-builder` / `knowledge-builder` / `wiki-writer` |
+| **Build skill** | `templates/_shared/build-skills/` | `harness-build-skill-<name>.md` | `skills-main` / `orchestrator` / `spec-builder` / `references-intake` / `agent-env-merge` / `knowledge-builder` / `wiki-writer` |
 | **Build rule** | `templates/_shared/build-rules/` | `harness-build-rule-<name>.md` | `agent-agnostic` / `chinese-only` / `memory-write` / `orchestrator-flow` / `skills-tasks-output` / `specs-schema` / `user-interaction` |
 
 约束：
@@ -127,26 +182,60 @@ harness-build-{skill|rule}-<semantic-name>
 
 | 阶段 | 动作 | 产物 |
 |------|------|------|
-| **P1_wiki** | 构建 baseline wiki（仅当有 baseline 时出现，项目经验底座） | `assets/baseline/wiki/` |
-| **P2_raw** | 用户放入需求文档（可参考 wiki） | `assets/raw/` |
-| **P3** | 条目化需求 | `assets/requirements/*.requirements.yaml` |
-| **P4** | 生成规格 | `specs/<layer>/<module>.<layer>.yaml` + schema 校验 |
-| **P5** | 规则 + 知识提取 | `agent-env/rules/` + `baseline/code/SAMPLES.md` |
-| **P6** | Skills & tasks 索引 | `agent-env/skills/` + `tasks/templates/` |
-| **P7** | Memory 初始化 | `agent-env/memory/categories/` |
-| **P-Final** | 封板 | 版本 bump + CHANGELOG + 终审 |
+| **S10_wiki** | 构建 baseline wiki（仅当有 baseline 时出现，项目经验底座） | `baseline/wiki/` |
+| **S20_collect_inputs** | 添加相关文件：需求/参考文档 + 额外运行期资源征询（`--extra-skills` 单入口，可混放 skills/rules） | `requirements/raw/` + `references/raw/` + `agent-env/_incoming/skills/` |
+| **S30_convert_docs** | 非 Markdown 原始文档转 Markdown | `requirements/md/` + `references/md/` |
+| **S40_extract_requirements** | 条目化需求 | `requirements/yaml/*.yaml` |
+| **S50_generate_specs** | 生成规格 | `specs/<layer>/<module>.<layer>.yaml` + schema 校验 |
+| **S60_process_references** | references 处理（`svharness convert` + 结构化索引 + 用户确认落地） | `references/md/` |
+| **S61_confirm_baseline_extraction** | 确认是否自动从 baseline 提取 skills/rules（表单确认） | `.harness-build-state.yaml`（`phases.S61_confirm_baseline_extraction.baseline_auto_extract`） |
+| **S65_customize_agent_env** | agent-env 定制（extra-skills/extra-rules 冲突建议与重命名建议 → 用户确认 → 写入） | `agent-env/rules/` + `agent-env/skills/` |
+| **S70_runtime_assets** | 运行期 Skills & tasks 索引（skill 执行 task） | `agent-env/skills/` + `tasks/templates/` |
+| **S80_seed_memory** | Memory 初始化 | `agent-env/memory/categories/` |
+| **S90_finalize** | 封板 | 版本 bump + CHANGELOG + 终审 |
 
 > 反复调用 orchestrator 总是从"第一个非 DONE 的阶段"继续。
-> **P1_wiki 仅在有 baseline 时出现；无 baseline 则不构建 wiki，流程从 P2_raw 开始。**
-> **P2_raw 必须等待用户放入需求文档，Agent 不得自行生成占位文件。**
+> **S10_wiki 仅在有 baseline 时出现；无 baseline 则不构建 wiki，流程从 S20_collect_inputs 开始。**
+> **S20_collect_inputs 必须等待用户放入需求文档，且需显式征询 references 与额外运行期资源输入（`--extra-skills`，可混放 skills/rules）；Agent 不得自行生成占位文件。若 build 传入了 `--requirements/--references`，CLI 会在拷贝到 raw 后自动尝试 convert 到 md。**
+> **S60_process_references 专注 references：必须执行 `svharness convert`，并产出结构化索引（规制约束 / skills 候选 / signals / manuals），经表单确认后再进入后续阶段。**
+> **S61_confirm_baseline_extraction 必须显式确认是否启用 baseline 自动提取 skills/rules；未经确认不得在 S65 自动提取。**
+> **S65_customize_agent_env 专注 extra-skills/extra-rules：来源可来自 `--extra-skills` 导入后的 `_incoming/manifest.yaml`，先冲突识别与重命名建议，再表单确认写入；推荐命名：`harness-apply-skills-<topic>` 与 `harness-apply-rules-<topic>.md/.mdc`。**
 
 ---
 
 ## 命令参考
 
+### `wizard` —— 交互式向导（v0.10+）
+
+```bash
+svharness wizard
+```
+
+分步选择 `build` / `apply` / `convert`，填写路径与可选说明，最后保存到 `svharness.config.yaml` 和/或立即执行对应命令。
+
+### 配置文件 `svharness.config.yaml`（v0.10+）
+
+| 顶层字段 | 说明 |
+|----------|------|
+| `version` | 固定为 `1` |
+| `defaults` | 各命令共享默认（`arch` / `agent` / `yes` 等） |
+| `build` | 对应 `svharness build` |
+| `apply` | 对应 `svharness apply` |
+| `convert` | 对应 `svharness convert` |
+
+`build` 节除路径外，可写人类可读说明（仅写入配置文件，供团队阅读）：
+
+| 字段 | 说明 |
+|------|------|
+| `requirementsNote` | 需求文档业务说明 |
+| `referencesNote` | 参考资料说明 |
+| `extraSkillsNote` | 额外 skills/rules 说明 |
+
+完整示例见 [`templates/svharness.config.example.yaml`](templates/svharness.config.example.yaml)。
+
 ### `build` —— 构建 harness（v0.8 起的主命令）
 
-> 旧名 `svharness init`（以及 `svharnessbuild init`）作为兼容别名保留，调用时会打印 deprecation 警告。
+> 旧名 `svharness init`（以及 `svharness build`）作为兼容别名保留，调用时会打印 deprecation 警告。
 
 #### 交互式
 
@@ -170,14 +259,24 @@ svharness build \
 
 | 参数 | 是否必填 | 说明 | 默认值 |
 |------|----------|------|--------|
-| `--harness-name <name>` | ✅ 必填 | harness 名称（小写字母、数字、中连线），生成 `<name>-harness/` 目录 | — |
+| `--config <path>` | 可选 | 读取 YAML/JSON 配置；省略时在 cwd 查找 `svharness.config.yaml` | — |
+| `--save-config [path]` | 可选 | build 成功后把参数写入配置文件 | — |
+| `--harness-name <name>` | ✅ 必填* | harness 名称；可在 `build.harnessName` 中提供 | — |
 | `--name <name>` | ⚠️ 已废弃别名 | 等同 `--harness-name`，下个 minor 版本移除 | — |
 | `--arch <arch>` | 可选 | 架构模板：`android-compose` / `android-xml` / `cpp` / `web-react` / `python` | `android-compose` |
-| `--agent <agent>` | 可选 | 目标 Agent IDE：`codechat` / `qoder` / `cursor` / `claude-code` / `generic` | `codechat` |
+| `--agent <agent>` | 可选 | 目标 Agent IDE：`codechat` / `qoder` / `cursor` / `claude-code` / `opencode` / `generic` | `codechat` |
 | `--baseline <path\|url>` | 可选 | 基线来源：本地目录 **或** git 仓库 URL | — |
+| `--requirements <path>` | 可选 | 需求输入路径（文件或目录）；build 阶段**扁平**拷贝到 `requirements/raw/`（不保留源目录里的 `assets/raw/converted_md` 等嵌套），随后自动 convert 到 `requirements/md/`（失败仅告警，不中断 build） | — |
+| `--references <path>` | 可选 | 参考资料输入路径（文件或目录）；build 阶段**扁平**拷贝到 `references/raw/`，随后自动 convert 到 `references/md/`（失败仅告警，不中断 build） | — |
+| `--extra-skills <path...>` | 可选 | 额外运行期资源输入（文件/目录/glob，可混放 skills/rules）；build 阶段先拷贝到 `agent-env/_incoming/skills/` 并生成 `agent-env/_incoming/manifest.yaml`，S65 再分流写入 `skills/` 与 `rules/` | — |
 | `--baseline-branch <name>` | 可选 | git 基线的分支名（仅 git 模式有效） | `main` |
 | `--baseline-max-file-kb <kb>` | 可选 | 基线拷贝单文件大小上限（KB） | `1024` |
-| `--force` | 可选 flag | 覆写已存在的 harness 目录 | `false` |
+| `--convert-endpoint <url>` | 可选 | build 自动 convert 使用的 markitdown 服务基址；省略时读环境变量 `SVHARNESS_MARKITDOWN_ENDPOINT` | `http://markitdown.desaysz.site` |
+| `--convert-concurrency <n>` | 可选 | build 自动 convert 并发上传数 | `3` |
+| `--convert-max-file-mb <n>` | 可选 | build 自动 convert 单文件大小上限（MB） | `50` |
+| `--convert-timeout-sec <n>` | 可选 | build 自动 convert 请求超时秒数 | `120` |
+| `--convert-force` | 可选 flag | build 自动 convert 覆盖同名 `.md`（否则按 `-1/-2` 追加） | `false` |
+| `--force` | 可选 flag | 覆写已存在的 harness 目录；同时覆写项目根 `AGENTS.md` / `CLAUDE.md`（若存在） | `false` |
 | `-y, --yes` | 可选 flag | 跳过所有提示，采用默认值 | `false` |
 | `--verbose` | 可选 flag | 打印每个生成文件 | `false` |
 
@@ -191,13 +290,13 @@ svharness build \
 | `--wiki-model <name>` | LLM 模型名 | `Qwen3.6-27B`（来自内置 wiki 配置链） |
 | `--wiki-base-url <url>` | OpenAI 兼容 API 地址 | `http://model-api.desaysv.com/v1` |
 | `--wiki-api-key <key>` | API Key | 环境变量 `OPENAI_API_KEY` → `.env` → 内置默认 |
-| `--wiki-source <path>` | wiki 扫描的仓库根路径 | `<target>/assets/baseline/code/`（无 baseline 时为 cwd） |
+| `--wiki-source <path>` | wiki 扫描的仓库根路径 | `<target>/baseline/code/`（无 baseline 时为 cwd） |
 
 **Wiki 配置优先级**：CLI 参数 > 环境变量 > `.env` 文件 > 内置默认值
 
 **Wiki 模式总览**：
 
-| 组合 | 行为 | P1_wiki 状态 |
+| 组合 | 行为 | S10_wiki 状态 |
 |------|------|---------|
 | 无 `--baseline` | 不生成 wiki | phase 不存在 |
 | `--baseline`（默认） | 一次 LLM 拿 outline，写 `TASKS.md` | `PENDING` + `requires_agent: true` |
@@ -229,6 +328,17 @@ svharness apply --harness ../my-app-harness --target ./to-apply-project --clone
 
 **在 Agent IDE 中触发**：对话框输入 `应用 harness-apply-skills-main 完成 xxx 功能开发`，dispatcher 会自动加载 rules、扫描 skills、路由到合适的子能力。
 
+同时，CLI 会在**目标项目根**写入 `CLAUDE.md`（`--agent codechat` 或 `claude-code`）或 `AGENTS.md`（`qoder` / `cursor` / `opencode` / `generic`），指向 **harness-apply-skills-main** 与 `AGENTS_APPLY.md`（与 `build` 写入项目根入口的规则一致）。
+
+#### references 内容引用 → apply_skill_registry（S60，由 Agent 写入）
+
+S60（`harness-build-skill-references-intake`）中，若某份 references 属于**内容引用**（apply 时要按 `references/md/` 原文指导开发），Agent 应：
+
+1. 登记 `references/apply-skills-registry.yaml`（`skill_name`、`reference_md`、`description`，可选 `entry` / `source_id`）
+2. 执行 `svharness apply` 时，CLI 将 enabled 项写入 `harness-apply-skills-main` 绑定元数据的 `apply_skill_registry`；运行期由 apply-main 读 registry + `references/md/` 路由，**不向目标项目注入** `harness-apply-skills-*` 子目录
+
+无单独 CLI；规制约束、纯手册类 references **不**登记 registry。
+
 #### 双模式对比
 
 | 模式 | 标志 | harness 位置 | binding.yaml `mode` | 适用场景 |
@@ -242,9 +352,9 @@ svharness apply --harness ../my-app-harness --target ./to-apply-project --clone
 |------|----------|------|--------|
 | `--harness <path>` | ✅ 必填 | 已构建好的 harness 目录（形如 `./my-app-harness`） | — |
 | `--target <path>` | 可选 | 目标项目根目录 | **当前工作目录（cwd）** |
-| `--agent <agent>` | 可选 | 目标 Agent：`codechat` / `qoder` / `cursor` / `claude-code` / `generic` | **从 `<harness>/.harness-build-state.yaml` 读取**；缺失则报错 |
+| `--agent <agent>` | 可选 | 目标 Agent：`codechat` / `qoder` / `cursor` / `claude-code` / `opencode` / `generic` | **从 `<harness>/.harness-build-state.yaml` 读取**；缺失则报错 |
 | `--clone` | 可选 flag | 完整拷贝 harness 到目标项目根下 | `false`（即 bind-only） |
-| `--force` | 可选 flag | 覆盖已存在的 dispatcher skill 目录（clone 模式下同时覆盖克隆目标） | `false` |
+| `--force` | 可选 flag | 覆盖已存在的 dispatcher skill 目录（clone 模式下同时覆盖克隆目标）；并覆盖项目根 `CLAUDE.md`/`AGENTS.md` 与 `AGENTS_APPLY.md` | `false` |
 | `-y, --yes` | 可选 flag | 跳过交互确认 | `false` |
 | `--verbose` | 可选 flag | 显示详细日志 | `false` |
 
@@ -252,6 +362,8 @@ svharness apply --harness ../my-app-harness --target ./to-apply-project --clone
 
 ```
 <target>/
+├── CLAUDE.md | AGENTS.md           # apply 工作流入口（按 --agent；已存在时默认跳过）
+├── AGENTS_APPLY.md                 # harness 应用指南（harness 内模板生成后拷贝）
 ├── <adapter.skillsDir>/harness-apply-skills-main/
 │   ├── SKILL.{md|mdc}              # dispatcher skill 本体（含 frontmatter 触发词
 │   │                               #   + 末尾 ## 绑定元数据 内嵌 YAML 块，权威来源）
@@ -277,6 +389,70 @@ applied_by: svharness@0.8.0
 > - 同路径自拷贝会被自动跳过（防御性校验）。
 > - `--agent` 省略时从 harness 构建状态文件读取，确保与原 IDE 一致；若状态文件缺失则报错。
 
+### `convert` —— 文档 → Markdown 预处理（对接 S20_collect_inputs）
+
+把本地原始需求文档（`.pdf / .docx / .pptx / .xlsx / .html / .epub / .txt / .csv / .json / ...`）通过**云端部署**的 `markitdown_serve`（FastAPI + Microsoft MarkItDown）批量转为 Markdown，产物统一落到 `<harness>/<type>/md/`（`type` 为 `requirements` 或 `references`），直接喂给下游 `S40_extract_requirements` 条目化流程，显著提升 specs 生成质量的稳定性。
+
+> **架构约束**：CLI 只是 HTTP 客户端，**不 spawn / 不装 Python / 不管进程**。服务端代码集中在 `svharnessbuild/markitdown_serve/` 便于仓内维护，但**不随 npm 包分发**，部署方式详见 [markitdown_serve/README.md](./markitdown_serve/README.md)。
+
+```bash
+# 最简 —— 所有参数均可省略，默认扫描当前目录
+svharness convert
+
+# 指定输入和输出目录
+svharness convert --input ./docs/*.pdf ./specs/ --output . --yes
+
+# 显示处理日志
+svharness convert --verbose
+```
+
+#### 全部参数
+
+| 参数 | 说明 | 默认值 |
+|------|------|--------|
+| `--input <path...>` | 一个或多个源文件 / 目录 / glob，支持 `./a/*.pdf`、`./docs/**/*.docx`、`./{a,b}/*.md` | `.`（当前目录） |
+| `--harness <path>` | 目标 harness 目录（需包含 `harness.yaml`）；省略时等同 `--output` | `--output` 值 |
+| `--output <path>` | Markdown 输出基目录，产物落到 `<harness>/<type>/md/` | `.`（当前目录） |
+| `--endpoint <url>` | 云端 `markitdown_serve` 基址，省略时读环境变量 `SVHARNESS_MARKITDOWN_ENDPOINT` | `http://markitdown.desaysz.site` |
+| `--concurrency <n>` | 并发上传数 | `3` |
+| `--max-file-mb <n>` | 单文件大小上限（MB），本地 + 服务端双重限流 | `50` |
+| `--timeout-sec <n>` | 单请求超时秒数 | `120`（2 分钟） |
+| `--type <type>` | 目标子目录：`requirements`（正式需求）\| `references`（参考资料） | `requirements` |
+| `--force` | flag，覆盖已存在同名 `.md`（默认自动追加 `-1`、`-2` 后缀） | `false` |
+| `-y, --yes` | flag，跳过交互确认 | `false` |
+| `--verbose` | flag，显示详细日志 | `false` |
+
+#### 行为要点
+
+- **健康探针前置**：上传前先 `GET /healthz`，不通直接退出并打印清晰定位指引（endpoint / 环境变量 / 服务端目录三条线索）。
+- **单文件失败不中断**：失败单文件计入汇总，其它文件照常完成。结束时打印 `ok / skipped / failed` 计数。
+- **本地白名单预过滤**：客户端与服务端的扩展名白名单保持一致，非白名单文件本地直接跳过，避免无意义往返。
+- **产物目录固定**：Markdown 只写入 `<harness>/<type>/md/`；扫描 `raw/` 时会跳过 `converted_md/`、`md/`、`yaml/` 等目录，并在结束后把误落在 `raw/**/converted_md/` 下的 `.md` 自动迁回 `<type>/md/`。
+- **只写入 `--output` 指定目录**：原文件不移动、不删除，便于用户回溯。
+
+#### 产物
+
+```
+<harness>/
+└── requirements/          # --type requirements（默认）
+│   └── md/
+│       ├── 需求.md
+│       └── ...
+└── references/            # --type references
+    └── md/
+        ├── 参考文档.md
+        └── ...
+```
+
+#### 接口契约（CLI ⇄ markitdown_serve）
+
+| 端点 | 方法 | 约定 |
+|---|---|---|
+| `/healthz` | GET | 200 `{status, markitdown_version}` |
+| `/convert` | POST | multipart/form-data，字段 `file`；200 返回 `{markdown, source_name, mime}`；413/415/500 带结构化 `error` 字段 |
+
+完整契约与部署说明见 [markitdown_serve/README.md](./markitdown_serve/README.md)。
+
 ---
 
 ## 架构模板
@@ -364,6 +540,11 @@ svharness build --harness-name my-app --yes
 # 显式指定全部参数
 svharness build --harness-name my-app --arch android-compose --agent qoder --yes
 
+# 额外运行期资源（单入口，可混放 skills/rules，先入 _incoming）
+svharness build \
+  --harness-name my-app --arch android-compose --agent codechat \
+  --extra-skills ./extras ./rules/*.mdc --yes
+
 # 本地基线 + wiki 生成
 svharness build \
   --harness-name my-app --arch android-compose --agent codechat \
@@ -493,6 +674,61 @@ pwsh -File .\scripts\smoke-test.ps1
 
 构建 TS → 临时目录 `build` → 校验文件 → `--force` 覆写验证。
 
+### 演示与 `--extra-skills` 验收
+
+端到端演示（requirements + references + baseline + extra-skills 混放）见 **[`demo_project/README.md`](./demo_project/README.md)**。在 `svharnessbuild/` 下：
+
+```powershell
+svharness build --harness-name demo-py --arch python --agent codechat `
+  --baseline ./demo_project/baseline `
+  --requirements ./demo_project/requirements `
+  --references ./demo_project/references `
+  --extra-skills ./demo_project/extra-skills `
+  --yes --force
+```
+
+`demo_project/extra-skills/` 布局：
+
+| 路径 | intake `detected_type` |
+|------|------------------------|
+| `harness-apply-skills-test-generator/SKILL.md` | `skill` |
+| `harness-apply-skills-python-code-review/SKILL.md` | `skill` |
+| `harness-apply-rules-demo-calculator.mdc` | `rule` |
+| `unknown-sample/readme.txt` | `unknown`（S65 需人工确认） |
+
+**分项验收**（仅测 extra-skills 某一类时）：
+
+```powershell
+# 1) 纯 skills（两个目录，可重复 --extra-skills）
+svharness build --harness-name demo-skills --arch python --agent codechat `
+  --extra-skills ./demo_project/extra-skills/harness-apply-skills-test-generator `
+  --extra-skills ./demo_project/extra-skills/harness-apply-skills-python-code-review `
+  --yes --force
+
+# 2) 纯 rule
+svharness build --harness-name demo-rules --arch python --agent codechat `
+  --extra-skills ./demo_project/extra-skills/harness-apply-rules-demo-calculator.mdc `
+  --yes --force
+
+# 3) skills + rules 混放（与端到端相同目录）
+svharness build --harness-name demo-mixed --arch python --agent codechat `
+  --extra-skills ./demo_project/extra-skills --yes --force
+
+# 4) unknown 资源（需 S65 人工确认类型）
+svharness build --harness-name demo-unknown --arch python --agent codechat `
+  --extra-skills ./demo_project/extra-skills/unknown-sample/readme.txt `
+  --yes --force
+```
+
+验收观察点：
+
+- `agent-env/_incoming/skills/` 已导入输入资源；
+- `agent-env/_incoming/manifest.yaml` 包含 `detected_type` 与 `suggested_name`；
+- `.harness-build-state.yaml` 的 `S65_customize_agent_env` 已回填 `incoming_total/skills_count/rules_count/unknown_count`；
+- unknown 或冲突资源仅在 S65 表单确认后落入 `agent-env/skills/` 或 `agent-env/rules/`。
+
+> 历史 `fixtures/` 目录已移除，统一由 `demo_project/` 承担演示与 intake 验收。
+
 ### 注意事项
 
 1. **shebang**：`bin/cli.js` 首行必须为 `#!/usr/bin/env node`

package/dist/adapters/claude-code.js

@@ -4,6 +4,7 @@ exports.claudeCodeAdapter = void 0;
 const _frontmatter_1 = require("./_frontmatter");
 exports.claudeCodeAdapter = {
     name: 'claude-code',
+    projectEntryFile: 'CLAUDE.md',
     skillsDir: '.claude/skills',
     skillExt: '.md',
     rulesDir: '.claude/rules',

package/dist/adapters/codechat.js

@@ -4,6 +4,7 @@ exports.codechatAdapter = void 0;
 const _frontmatter_1 = require("./_frontmatter");
 exports.codechatAdapter = {
     name: 'codechat',
+    projectEntryFile: 'CLAUDE.md',
     skillsDir: '.codechat/skills',
     skillExt: '.md',
     rulesDir: '.codechat/rules',

package/dist/adapters/cursor.js

@@ -8,6 +8,7 @@ const _frontmatter_1 = require("./_frontmatter");
  */
 exports.cursorAdapter = {
     name: 'cursor',
+    projectEntryFile: 'AGENTS.md',
     skillsDir: '.cursor/rules',
     skillExt: '.mdc',
     transform: (0, _frontmatter_1.ensureMdcFrontmatter)('Harness build helper skill'),

package/dist/adapters/generic.js

@@ -11,6 +11,7 @@ const _frontmatter_1 = require("./_frontmatter");
  */
 exports.genericAdapter = {
     name: 'generic',
+    projectEntryFile: 'AGENTS.md',
     skillsDir: '.harness/skills',
     skillExt: '.md',
     rulesDir: '.harness/rules',

package/dist/adapters/index.js

@@ -7,11 +7,13 @@ const qoder_1 = require("./qoder");
 const cursor_1 = require("./cursor");
 const claude_code_1 = require("./claude-code");
 const generic_1 = require("./generic");
+const opencode_1 = require("./opencode");
 const REGISTRY = {
     codechat: codechat_1.codechatAdapter,
     qoder: qoder_1.qoderAdapter,
     cursor: cursor_1.cursorAdapter,
     'claude-code': claude_code_1.claudeCodeAdapter,
+    opencode: opencode_1.opencodeAdapter,
     generic: generic_1.genericAdapter,
 };
 function getAdapter(name) {

package/dist/adapters/opencode.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.opencodeAdapter = void 0;
+const _frontmatter_1 = require("./_frontmatter");
+/**
+ * OpenCode (opencode.ai): project skills under `.opencode/skills/<name>/SKILL.md`.
+ * @see https://opencode.ai/docs/skills
+ */
+exports.opencodeAdapter = {
+    name: 'opencode',
+    projectEntryFile: 'AGENTS.md',
+    skillsDir: '.opencode/skills',
+    skillExt: '.md',
+    rulesDir: '.opencode/rules',
+    ruleExt: '.mdc',
+    ruleTransform: (0, _frontmatter_1.ensureMdcFrontmatter)('Harness build-time rule'),
+};

package/dist/adapters/qoder.js

@@ -4,6 +4,7 @@ exports.qoderAdapter = void 0;
 const _frontmatter_1 = require("./_frontmatter");
 exports.qoderAdapter = {
     name: 'qoder',
+    projectEntryFile: 'AGENTS.md',
     skillsDir: '.qoder/skills',
     skillExt: '.md',
     rulesDir: '.qoder/rules',

package/dist/commands/apply.js

@@ -9,6 +9,8 @@ const node_path_1 = __importDefault(require("node:path"));
 const js_yaml_1 = __importDefault(require("js-yaml"));
 const prompts_1 = __importDefault(require("prompts"));
 const adapters_1 = require("../adapters");
+const apply_project_entry_1 = require("../core/apply-project-entry");
+const reference_apply_skills_1 = require("../core/reference-apply-skills");
 const validate_args_1 = require("../utils/validate-args");
 const logger_1 = require("../utils/logger");
 const version_1 = require("../utils/version");
@@ -131,8 +133,9 @@ async function runApply(opts) {
         }
     }
     if (!agent) {
-        throw new Error('无法推断目标 agent。请显式传入 --agent <codechat|qoder|cursor|claude-code|generic>，' +
-            '或确认 harness 下存在 .harness-build-state.yaml。');
+        throw new Error('无法推断目标 agent。请显式传入 --agent <' +
+            (0, validate_args_1.listSupportedAgents)().join('|') +
+            '>，或确认 harness 下存在 .harness-build-state.yaml。');
     }
     const adapter = (0, adapters_1.getAdapter)(agent);
     // 4. Compute injection target.
@@ -165,7 +168,7 @@ async function runApply(opts) {
     if (cloneMode && effectiveHarnessRoot !== harnessRoot) {
         configRows.push({ label: '克隆目标', value: effectiveHarnessRoot });
     }
-    configRows.push({ label: '注入 skill', value: node_path_1.default.relative(targetRoot, skillFile) }, { label: '绑定元数据（冗余副本）', value: node_path_1.default.relative(targetRoot, bindingFile) }, { label: '工具版本', value: `svharness@${cliVersion}` });
+    configRows.push({ label: '注入 skill', value: node_path_1.default.relative(targetRoot, skillFile) }, { label: '绑定元数据（冗余副本）', value: node_path_1.default.relative(targetRoot, bindingFile) }, { label: '项目根 AI 入口', value: adapter.projectEntryFile }, { label: '工具版本', value: `svharness@${cliVersion}` });
     logger_1.logger.configBox('apply 配置确认', configRows);
     if (!opts.yes) {
         const { ok } = await (0, prompts_1.default)({
@@ -209,6 +212,10 @@ async function runApply(opts) {
     }
     // 8. Build binding metadata first (needed for both inline rendering into
     //    the skill body and the redundant sidecar file).
+    const skillRegistry = await (0, reference_apply_skills_1.loadApplySkillRegistry)(effectiveHarnessRoot);
+    const applySkillRegistry = skillRegistry
+        ? (0, reference_apply_skills_1.registryEntriesForBinding)(skillRegistry)
+        : [];
     const binding = {
         harness_name: harnessName,
         harness_root: effectiveHarnessRoot,
@@ -219,6 +226,7 @@ async function runApply(opts) {
         mode: cloneMode ? 'clone' : 'bind-only',
         applied_at: appliedAt,
         applied_by: `svharness@${cliVersion}`,
+        apply_skill_registry: applySkillRegistry,
     };
     const bindingYaml = '# Generated by `svharness apply`. DO NOT edit by hand.\n' +
         '# Re-run `svharness apply --force` to refresh.\n' +
@@ -253,12 +261,49 @@ async function runApply(opts) {
     logger_1.logger.section(`步骤 ${stepNo}/${totalSteps} - 写入 harness 绑定元数据（冗余副本）`);
     await fs_extra_1.default.outputFile(bindingFile, bindingYaml, 'utf8');
     logger_1.logger.success(`已写入 ${node_path_1.default.relative(targetRoot, bindingFile)}（冗余副本）`);
+    if (applySkillRegistry.length > 0) {
+        logger_1.logger.success(`已内联 apply_skill_registry ${applySkillRegistry.length} 条（references 内容由 apply-main 路由）`);
+    }
+    else {
+        logger_1.logger.info('未找到 references/apply-skills-registry.yaml，apply_skill_registry 为空');
+        logger_1.logger.info('  请在 S60 为「内容引用」登记 registry 后重新 apply');
+    }
+    // 9b. Inject AGENTS_APPLY.md into target project root (if present in harness).
+    const agentsApplySrc = node_path_1.default.join(harnessRoot, 'AGENTS_APPLY.md');
+    if (await fs_extra_1.default.pathExists(agentsApplySrc)) {
+        const agentsApplyDest = node_path_1.default.join(targetRoot, 'AGENTS_APPLY.md');
+        let shouldCopy = true;
+        if (await fs_extra_1.default.pathExists(agentsApplyDest)) {
+            if (!opts.force) {
+                logger_1.logger.warn(`目标项目已存在 AGENTS_APPLY.md，跳过（使用 --force 覆盖）`);
+                shouldCopy = false;
+            }
+        }
+        if (shouldCopy) {
+            await fs_extra_1.default.copy(agentsApplySrc, agentsApplyDest, { overwrite: true });
+            logger_1.logger.success(`已写入 ${node_path_1.default.relative(targetRoot, agentsApplyDest)}`);
+        }
+    }
+    else {
+        logger_1.logger.debug('harness 中未找到 AGENTS_APPLY.md，跳过注入');
+    }
+    await (0, apply_project_entry_1.writeApplyProjectEntry)({
+        projectRoot: targetRoot,
+        adapter,
+        harnessRootRel,
+        harnessName,
+        harnessVersion,
+        agent,
+        mode: cloneMode ? 'clone' : 'bind-only',
+        force: !!opts.force,
+    });
     // 10. Next steps hint.
     logger_1.logger.plain('');
     logger_1.logger.plain('✨ harness 已绑定到当前项目');
     logger_1.logger.plain('');
     logger_1.logger.plain('  下一步：在 agent 中输入');
     logger_1.logger.plain(`    应用 ${DISPATCHER_SKILL_NAME} 完成 <你的功能> 功能开发`);
+    logger_1.logger.plain(`  或阅读 ${adapter.projectEntryFile} 与 AGENTS_APPLY.md 了解完整的 harness 应用工作流`);
     logger_1.logger.plain('');
     if (cloneMode && effectiveHarnessRoot !== harnessRoot) {
         logger_1.logger.plain(`  harness 内容已克隆至：${node_path_1.default.relative(targetRoot, effectiveHarnessRoot)}/（已纳入目标项目）`);