svharness 0.8.0 → 0.13.2

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` |
@@ -217,24 +316,39 @@ svharness build \
 
 ### `apply` —— 把已构建好的 harness 绑定到目标项目
 
-把 `<name>-harness/`（通过 `build` + orchestrator 构建完成的知识层）**以最小侵入方式**应用到任意目标项目：向该项目的 Agent IDE skill 目录注入一个 **dispatcher skill**（`harness-apply-skills-main`），由它在运行期**从 skill 正文内嵌的 `## 绑定元数据` 块**定位 harness 并路由到具体能力。`references/binding.yaml` 作为冗余副本同时写入，仅供 `svharness` 自身工具链（status / detach / re-apply 检测）解析，运行时 dispatcher 不读它。
+把 `<name>-harness/`（通过 `build` 完成的知识层）应用到目标项目时，`apply` 现采用**默认复制模式**：始终把 harness 拷贝到 `<target>/<name>-harness/`，然后注入 runtime skills/rules，并生成项目根 AI 入口。
 
 ```bash
-# bind-only（默认）—— 仅注入 dispatcher skill，harness 保留在原位置
+# 默认复制模式（无需 --clone）
 svharness apply --harness ../my-app-harness --target ./to-apply-project
 
-# clone —— 把整个 harness 完整拷贝到目标项目根下，binding.yaml 指向本地副本
+# --clone 仍可传入，但仅兼容：行为与默认一致（都会拷贝）
 svharness apply --harness ../my-app-harness --target ./to-apply-project --clone --yes
 ```
 
-**在 Agent IDE 中触发**：对话框输入 `应用 harness-apply-skills-main 完成 xxx 功能开发`，dispatcher 会自动加载 rules、扫描 skills、路由到合适的子能力。
+**在 Agent IDE 中触发**：对话框输入 `应用 harness-apply-skills-main 完成 xxx 功能开发`，薄入口会提示并优先使用已注入的 `harness-apply-skills-*` 子 skill。
+
+同时，CLI 会在**目标项目根**写入 `CLAUDE.md`（`--agent codechat` 或 `claude-code`）或 `AGENTS.md`（`qoder` / `cursor` / `opencode` / `generic`）。该入口由 `<harness>/AGENTS_APPLY.md` 拷贝并重命名生成（与 `build` 写入项目根入口的规则一致，不再单独落地 `AGENTS_APPLY.md`）。
+
+此外，`apply` 会同步注入运行期资产：
 
-#### 双模式对比
+- `<harness>/agent-env/rules/` → `<target>/<adapter.rulesDir>/`（若该 agent 声明了 `rulesDir`）
+- `<harness>/agent-env/skills/` → `<target>/<adapter.skillsDir>/`（全量注入；`harness-apply-skills-main` 由模板写入为薄入口）
+- 目标 `.gitignore` 会追加注入路径（幂等去重）
 
-| 模式 | 标志 | harness 位置 | binding.yaml `mode` | 适用场景 |
-|------|------|-------------|--------------------|----------|
-| **bind-only** | 默认 | 保持在 `--harness` 原路径 | `bind-only` | harness 与多个目标项目共享、单一知识源 |
-| **clone** | `--clone` | 拷贝到 `<target>/<name>-harness/` | `clone` | 需要自包含交付、离线使用、锁定版本 |
+#### references 内容引用 → apply_skill_registry（S60，由 Agent 写入）
+
+S60（`harness-build-skill-references-intake`）属于 **build 阶段**。若某份 references 属于**内容引用**（apply 时要按 `references/md/` 原文指导开发），Agent 应：
+
+1. 登记 `references/apply-skills-registry.yaml`（`skill_name`、`reference_md`、`description`，可选 `entry` / `source_id`）
+2. 执行 `svharness apply` 时，运行期 skill 将按引用原文执行，且相关路径会改写到 `<target>/<name>-harness/` 下可达位置
+
+无单独 CLI；规制约束、纯手册类 references **不**登记 registry。
+
+#### build / apply 分工
+
+- **build 阶段**：生成 harness 本体资产（`AGENTS_APPLY.md`、`agent-env/skills`、`agent-env/rules`、`specs`、`baseline` 等）
+- **apply 阶段**：复制 harness 到目标项目、注入 skills/rules、生成入口文件、写 `.gitignore`、校验注入文件引用关系
 
 #### 全部参数
 
@@ -242,9 +356,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` 读取**；缺失则报错 |
-| `--clone` | 可选 flag | 完整拷贝 harness 到目标项目根下 | `false`（即 bind-only） |
-| `--force` | 可选 flag | 覆盖已存在的 dispatcher skill 目录（clone 模式下同时覆盖克隆目标） | `false` |
+| `--agent <agent>` | 可选 | 目标 Agent：`codechat` / `qoder` / `cursor` / `claude-code` / `opencode` / `generic` | **从 `<harness>/.harness-build-state.yaml` 读取**；缺失则报错 |
+| `--clone` | 可选 flag | 兼容参数；当前实现下行为与默认一致（都会拷贝 harness） | `false` |
+| `--force` | 可选 flag | 覆盖已存在注入目录与入口文件；同时允许重拷贝 harness | `false` |
 | `-y, --yes` | 可选 flag | 跳过交互确认 | `false` |
 | `--verbose` | 可选 flag | 显示详细日志 | `false` |
 
@@ -252,30 +366,85 @@ svharness apply --harness ../my-app-harness --target ./to-apply-project --clone
 
 ```
 <target>/
+├── CLAUDE.md | AGENTS.md           # apply 工作流入口（由 harness/AGENTS_APPLY.md 重命名）
+├── <adapter.rulesDir>/...          # 运行期 rules 注入（若 adapter 声明 rulesDir）
+├── <adapter.skillsDir>/<runtime-skill>/SKILL.{md|mdc}  # 运行期 skills 注入
 ├── <adapter.skillsDir>/harness-apply-skills-main/
-│   ├── SKILL.{md|mdc}              # dispatcher skill 本体（含 frontmatter 触发词
-│   │                               #   + 末尾 ## 绑定元数据 内嵌 YAML 块，权威来源）
-│   └── references/binding.yaml     # 冗余副本（权威源在 SKILL.md 内），供工具链解析
-└── <name>-harness/                 # 仅 --clone 模式
+│   └── SKILL.{md|mdc}              # 薄入口 skill（仅提示/索引，不做二级调度）
+└── <name>-harness/                 # apply 默认复制后的 harness
 ```
 
-dispatcher skill 末尾内嵌的 `## 绑定元数据` YAML 块即权威来源，`references/binding.yaml` 只是同字段的冗余副本。字段示例：
-
-```yaml
-harness_name: my-app
-harness_root: D:\abs\path\to\my-app-harness      # 运行时定位 harness 的绝对路径
-harness_root_rel: ../my-app-harness              # 相对 target 的路径（可读）
-harness_version: 0.1.0
-target_project: D:\abs\path\to\to-apply-project
-agent: codechat
-mode: bind-only                                  # 或 clone
-applied_at: '2026-05-12T13:34:54.184Z'
-applied_by: svharness@0.8.0
+> 注入完成后，CLI 会校验入口文件、薄入口 skill、注入 skills/rules 内的路径引用是否可达；失败会报错中止。
+
+### `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
+
+# 独立模式：md 直接写入 ./docs/md
+svharness convert --input ./docs/*.pdf --output ./docs/md --yes
+
+# harness 模式：md 写入 ./my-app-harness/requirements/md/
+svharness convert --input ./my-app-harness/requirements/raw --output ./my-app-harness --yes
+
+# 显示处理日志
+svharness convert --verbose
 ```
 
-> - clone 模式下 `harness_root` 指向克隆后的本地副本，而非 `--harness` 原路径。
-> - 同路径自拷贝会被自动跳过（防御性校验）。
-> - `--agent` 省略时从 harness 构建状态文件读取，确保与原 IDE 一致；若状态文件缺失则报错。
+#### 全部参数
+
+| 参数 | 说明 | 默认值 |
+|------|------|--------|
+| `--input <path...>` | 一个或多个源文件 / 目录 / glob，支持 `./a/*.pdf`、`./docs/**/*.docx`、`./{a,b}/*.md` | `.`（当前目录） |
+| `--harness <path>` | harness 根目录（需 `harness.yaml`）；单独使用时写入 `<harness>/<type>/md/`；与 `--output` 同用时 `--output` 为最终 md 目录 | — |
+| `--output <path>` | **独立模式**：最终 md 输出目录；**harness 模式**：`path` 含 `harness.yaml` 时写入 `<path>/<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` 计数。
+- **本地白名单预过滤**：客户端与服务端的扩展名白名单保持一致，非白名单文件本地直接跳过，避免无意义往返。
+- **两种输出模式**：
+  - **独立**：`--output` 即最终 md 目录（路径下无 `harness.yaml`），例如 `--output ./docs/md`。
+  - **harness**：`--output` 或 `--harness` 指向含 `harness.yaml` 的目录时，写入 `<harness>/<type>/md/`（build / Agent 模板沿用此约定）。
+- **harness 模式收尾**：扫描 `raw/` 时跳过 `converted_md/`、`md/` 等；结束后将误落在 `raw/**/converted_md/` 下的 `.md` 迁回 `<type>/md/`。
+- **源文件不改动**：只生成 md，不移动或删除原始文档。
+
+#### 产物
+
+```
+<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 +533,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 +667,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`
@@ -514,7 +743,7 @@ pwsh -File .\scripts\smoke-test.ps1
 - [x] 多架构模板（`android-compose` / `android-xml` / `cpp` / `web-react` / `python`）
 - [x] `_shared/` + `<arch>/` 两层叠拷合并
 - [x] 每个架构自带 3-5 条规则文件（`.mdc` 格式，`always_on` 加载）
-- [x] `apply` —— 把已构建好的 harness 绑定到目标项目（支持 `--clone` 双模式）
+- [x] `apply` —— 把已构建好的 harness 绑定到目标项目（默认复制模式，`--clone` 兼容保留）
 - [x] 构建辅助资源统一命名（`build-skills/harness-build-skill-*`、`build-rules/harness-build-rule-*`）
 - [ ] `detach` —— 从目标项目解绑并清理 dispatcher skill
 - [ ] `doctor` —— 检查既有 harness 的健康度

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',