svharness 0.11.0 → 0.13.3

package/README.md

@@ -316,35 +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-apply-skills-main** 与 `AGENTS_APPLY.md`（与 `build` 写入项目根入口的规则一致）。
+同时，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` 会追加注入路径（幂等去重）
 
 #### references 内容引用 → apply_skill_registry（S60，由 Agent 写入）
 
-S60（`harness-build-skill-references-intake`）中，若某份 references 属于**内容引用**（apply 时要按 `references/md/` 原文指导开发），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` 时，CLI 将 enabled 项写入 `harness-apply-skills-main` 绑定元数据的 `apply_skill_registry`；运行期由 apply-main 读 registry + `references/md/` 路由，**不向目标项目注入** `harness-apply-skills-*` 子目录
+2. 执行 `svharness apply` 时，运行期 skill 将按引用原文执行，且相关路径会改写到 `<target>/<name>-harness/` 下可达位置
 
 无单独 CLI；规制约束、纯手册类 references **不**登记 registry。
 
-#### 双模式对比
+#### build / apply 分工
 
-| 模式 | 标志 | harness 位置 | binding.yaml `mode` | 适用场景 |
-|------|------|-------------|--------------------|----------|
-| **bind-only** | 默认 | 保持在 `--harness` 原路径 | `bind-only` | harness 与多个目标项目共享、单一知识源 |
-| **clone** | `--clone` | 拷贝到 `<target>/<name>-harness/` | `clone` | 需要自包含交付、离线使用、锁定版本 |
+- **build 阶段**：生成 harness 本体资产（`AGENTS_APPLY.md`、`agent-env/skills`、`agent-env/rules`、`specs`、`baseline` 等）
+- **apply 阶段**：复制 harness 到目标项目、注入 skills/rules、生成入口文件、写 `.gitignore`、校验注入文件引用关系
 
 #### 全部参数
 
@@ -353,8 +357,8 @@ S60（`harness-build-skill-references-intake`）中，若某份 references 属
 | `--harness <path>` | ✅ 必填 | 已构建好的 harness 目录（形如 `./my-app-harness`） | — |
 | `--target <path>` | 可选 | 目标项目根目录 | **当前工作目录（cwd）** |
 | `--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 模式下同时覆盖克隆目标）；并覆盖项目根 `CLAUDE.md`/`AGENTS.md` 与 `AGENTS_APPLY.md` | `false` |
+| `--clone` | 可选 flag | 兼容参数；当前实现下行为与默认一致（都会拷贝 harness） | `false` |
+| `--force` | 可选 flag | 覆盖已存在注入目录与入口文件；同时允许重拷贝 harness | `false` |
 | `-y, --yes` | 可选 flag | 跳过交互确认 | `false` |
 | `--verbose` | 可选 flag | 显示详细日志 | `false` |
 
@@ -362,32 +366,15 @@ S60（`harness-build-skill-references-intake`）中，若某份 references 属
 
 ```
 <target>/
-├── CLAUDE.md | AGENTS.md           # apply 工作流入口（按 --agent；已存在时默认跳过）
-├── AGENTS_APPLY.md                 # harness 应用指南（harness 内模板生成后拷贝）
+├── 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
-```
-
-> - clone 模式下 `harness_root` 指向克隆后的本地副本，而非 `--harness` 原路径。
-> - 同路径自拷贝会被自动跳过（防御性校验）。
-> - `--agent` 省略时从 harness 构建状态文件读取，确保与原 IDE 一致；若状态文件缺失则报错。
+> 注入完成后，CLI 会校验入口文件、薄入口 skill、注入 skills/rules 内的路径引用是否可达；失败会报错中止。
 
 ### `convert` —— 文档 → Markdown 预处理（对接 S20_collect_inputs）
 
@@ -399,8 +386,11 @@ applied_by: svharness@0.8.0
 # 最简 —— 所有参数均可省略，默认扫描当前目录
 svharness convert
 
-# 指定输入和输出目录
-svharness convert --input ./docs/*.pdf ./specs/ --output . --yes
+# 独立模式：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
@@ -411,8 +401,8 @@ 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/` | `.`（当前目录） |
+| `--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` |
@@ -427,8 +417,11 @@ svharness convert --verbose
 - **健康探针前置**：上传前先 `GET /healthz`，不通直接退出并打印清晰定位指引（endpoint / 环境变量 / 服务端目录三条线索）。
 - **单文件失败不中断**：失败单文件计入汇总，其它文件照常完成。结束时打印 `ok / skipped / failed` 计数。
 - **本地白名单预过滤**：客户端与服务端的扩展名白名单保持一致，非白名单文件本地直接跳过，避免无意义往返。
-- **产物目录固定**：Markdown 只写入 `<harness>/<type>/md/`；扫描 `raw/` 时会跳过 `converted_md/`、`md/`、`yaml/` 等目录，并在结束后把误落在 `raw/**/converted_md/` 下的 `.md` 自动迁回 `<type>/md/`。
-- **只写入 `--output` 指定目录**：原文件不移动、不删除，便于用户回溯。
+- **两种输出模式**：
+  - **独立**：`--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，不移动或删除原始文档。
 
 #### 产物
 
@@ -750,7 +743,7 @@ svharness build --harness-name demo-unknown --arch python --agent codechat `
 - [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 的健康度