svharness 0.8.0

package/README.md

@@ -0,0 +1,531 @@
+# svharness
+
+> v0.8 重命名说明：CLI 包名由 `svharnessbuild` → `svharness`，子命令 `init` → `build`，参数 `--name` → `--harness-name`。
+> 旧名 `svharnessbuild` / `init` / `--name` 作为兼容别名保留至下一个 minor 版本，使用时会打印 deprecation 提示。
+
+**SDD-Driven Agent-Agnostic Coding Framework** 的脚手架命令行工具。
+
+为任何 Agent IDE（Qoder / Cursor / Claude Code 等）生成项目本地的 **harness** —— 一个规格驱动的知识层骨架，让 AI 协作开发有章可循。
+
+---
+
+## 快速开始
+
+### 安装
+
+```bash
+# 从 npm 安装（发布后）
+npm install -g svharness
+
+# 或从源码安装
+cd svharnessbuild && npm install && npm run build && npm link
+```
+
+要求 **Node.js ≥ 18**。
+
+### 30 秒上手
+
+```bash
+# 最简 —— 只填名字，其余取默认（arch=android-compose, agent=codechat）
+svharness build --harness-name my-app
+
+# 一行式 —— 跳过交互，直接生成
+svharness build --harness-name my-app --arch android-compose --agent qoder --yes
+
+# 把构建完成的 harness 应用到其它项目（绑定式，不拷贝）
+svharness apply --harness ./my-app-harness --target ../other-project --yes
+```
+
+生成完成后，在你的 Agent IDE 中说：
+- "运行 harness-build-skill-orchestrator"即可开始逐步填充内容；
+- 构建完成后在目标项目中说"应用 harness-apply-skills-main 完成 xxx 功能开发"即可调用 harness。
+
+---
+
+## 核心概念
+
+### Harness 是什么？
+
+Harness 是一个 **项目本地的知识层**，由两大部分组成：
+
+| 部分 | 位置 | 生命周期 | 说明 |
+|------|------|----------|------|
+| **Agent 注入目录** | `.qoder/` / `.codechat/` / `.cursor/` 等 | `build` 时创建，Agent 自动加载 | rules + build-skills |
+| **Harness 目录** | `<harness-name>-harness/` | `build` 创建骨架 → Agent 逐步填充 | specs / assets / agent-env / tasks |
+
+### 目录结构
+
+执行 `svharness build` 后生成：
+
+```
+<harness-name>-harness/
+├── harness.yaml                  # 入口清单（架构 / agent / schema 引用）
+├── AGENTS.md                     # 面向 Agent 的使用指南
+├── README.md                     # 面向人的项目概览
+├── VERSION
+├── CHANGELOG.md
+├── .harness-build-state.yaml     # 构建进度追踪（P1 … P-Final）
+│
+├── specs/                        # 契约层
+│   ├── signals/schema.json
+│   ├── ui/schema.json
+│   ├── behavior/schema.json
+│   └── interfaces/schema.json
+│
+├── assets/                       # 支撑素材（非契约）
+│   ├── raw/                      #   原始需求文档
+│   ├── requirements/             #   条目化后的需求
+│   └── baseline/
+│       ├── code/                 #   参考代码快照
+│       └── wiki/                 #   架构 wiki
+│
+├── agent-env/                    # Agent 运行期环境
+│   ├── rules/                    #   编码规则（.mdc，always_on 加载）
+│   ├── skills/                   #   运行期技能（SKILL.md + references/ + scripts/）
+│   ├── tools/                    #   项目本地脚本
+│   └── memory/                   #   Agent 长期记忆
+│
+├── commands/                     # 项目安装 / 升级命令
+└── tasks/                        # 可复用的开发者工作流
+```
+
+同时，CLI 会向 Agent IDE 的 skill 目录注入 **4 个构建辅助 skill**：
+
+| Skill | 职责 |
+|-------|------|
+| `harness-build-skill-orchestrator` | 读取构建状态，路由到下一阶段 |
+| `harness-build-skill-spec-builder` | raw → requirements → specs 管线 |
+| `harness-build-skill-knowledge-builder` | baseline 快照 / rules / skills 索引 |
+| `harness-build-skill-wiki-writer` | 按 TASKS.md 逐页撰写 wiki 正文 |
+
+`.harness-build-state.yaml` 跟踪进度，任何阶段可中断再续。
+
+#### 构建辅助 skill / rule 命名规范
+
+注入到 Agent IDE 的构建辅助资源遵循 **三段式** 命名，区别于项目自建的运行期 skill（`harness-<domain>-<topic>`）：
+
+```
+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 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` |
+
+约束：
+
+- 前缀 `harness-build-` 专属于 **构建期**（`build` / orchestrator 驱动 harness 骨架填充），与运行期 skill（`harness-<domain>-<topic>`、如 `harness-compose-ui`）及 `apply` 注入的 `harness-apply-skills-main` dispatcher 明确区分。
+- 文件内部 frontmatter `name`、一级 heading、交叉引用必须与文件名保持一致。
+- 新增同类资源时沿用此三段式，禁止回退到两段式（如旧名 `harness-orchestrator` / `harness-build-orchestrator-flow` 已废弃）。
+
+### 构建阶段
+
+`build` 只生成骨架。各阶段的**实际内容**由 Agent 借助注入的 skill 逐步填充：
+
+| 阶段 | 动作 | 产物 |
+|------|------|------|
+| **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 + 终审 |
+
+> 反复调用 orchestrator 总是从"第一个非 DONE 的阶段"继续。
+> **P1_wiki 仅在有 baseline 时出现；无 baseline 则不构建 wiki，流程从 P2_raw 开始。**
+> **P2_raw 必须等待用户放入需求文档，Agent 不得自行生成占位文件。**
+
+---
+
+## 命令参考
+
+### `build` —— 构建 harness（v0.8 起的主命令）
+
+> 旧名 `svharness init`（以及 `svharnessbuild init`）作为兼容别名保留，调用时会打印 deprecation 警告。
+
+#### 交互式
+
+```bash
+svharness build --harness-name my-app
+# 仅 --harness-name 必填；其余参数采用默认值，结束前会有一次确认提示
+```
+
+#### 非交互（CI / 脚本）
+
+```bash
+svharness build \
+  --harness-name my-app \
+  --arch android-compose \
+  --agent codechat \
+  --baseline ../my-baseline-repo \
+  --yes
+```
+
+#### 全部参数
+
+| 参数 | 是否必填 | 说明 | 默认值 |
+|------|----------|------|--------|
+| `--harness-name <name>` | ✅ 必填 | harness 名称（小写字母、数字、中连线），生成 `<name>-harness/` 目录 | — |
+| `--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` |
+| `--baseline <path\|url>` | 可选 | 基线来源：本地目录 **或** git 仓库 URL | — |
+| `--baseline-branch <name>` | 可选 | git 基线的分支名（仅 git 模式有效） | `main` |
+| `--baseline-max-file-kb <kb>` | 可选 | 基线拷贝单文件大小上限（KB） | `1024` |
+| `--force` | 可选 flag | 覆写已存在的 harness 目录 | `false` |
+| `-y, --yes` | 可选 flag | 跳过所有提示，采用默认值 | `false` |
+| `--verbose` | 可选 flag | 打印每个生成文件 | `false` |
+
+#### Wiki 参数
+
+| 参数 | 说明 | 默认值 |
+|------|------|--------|
+| `--generate-wiki` | build 时直接逐页生成完整 wiki（与 `--wiki-tasks-only` 互斥） | `false` |
+| `--wiki-tasks-only` | 仅生成 wiki outline + TASKS.md（兼容保留） | `false`（但有 `--baseline` 时为**隐式默认行为**） |
+| `--wiki-lang <zh\|en>` | wiki 语言 | `zh` |
+| `--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 配置优先级**：CLI 参数 > 环境变量 > `.env` 文件 > 内置默认值
+
+**Wiki 模式总览**：
+
+| 组合 | 行为 | P1_wiki 状态 |
+|------|------|---------|
+| 无 `--baseline` | 不生成 wiki | phase 不存在 |
+| `--baseline`（默认） | 一次 LLM 拿 outline，写 `TASKS.md` | `PENDING` + `requires_agent: true` |
+| `--baseline` + `--generate-wiki` | 逐页调用 LLM 生成完整 wiki | 初始 `DONE`；失败降级为 `PENDING` |
+
+> Wiki 生成失败不会回滚 harness 骨架，仅输出警告。
+
+### Agent 适配器
+
+| Agent | skill 目录 | 扩展名 | 额外处理 |
+|-------|-----------|--------|----------|
+| `codechat`（默认） | `.codechat/skills/` | `.md` | — |
+| `qoder` | `.qoder/skills/` | `.md` | — |
+| `cursor` | `.cursor/rules/` | `.mdc` | 自动注入 frontmatter |
+| `claude-code` | `.claude/skills/` | `.md` | — |
+| `generic` | `.agent/skills/` | `.md` | 中立回退 |
+
+### `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 不读它。
+
+```bash
+# bind-only（默认）—— 仅注入 dispatcher skill，harness 保留在原位置
+svharness apply --harness ../my-app-harness --target ./to-apply-project
+
+# clone —— 把整个 harness 完整拷贝到目标项目根下，binding.yaml 指向本地副本
+svharness apply --harness ../my-app-harness --target ./to-apply-project --clone --yes
+```
+
+**在 Agent IDE 中触发**：对话框输入 `应用 harness-apply-skills-main 完成 xxx 功能开发`，dispatcher 会自动加载 rules、扫描 skills、路由到合适的子能力。
+
+#### 双模式对比
+
+| 模式 | 标志 | harness 位置 | binding.yaml `mode` | 适用场景 |
+|------|------|-------------|--------------------|----------|
+| **bind-only** | 默认 | 保持在 `--harness` 原路径 | `bind-only` | harness 与多个目标项目共享、单一知识源 |
+| **clone** | `--clone` | 拷贝到 `<target>/<name>-harness/` | `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` |
+| `-y, --yes` | 可选 flag | 跳过交互确认 | `false` |
+| `--verbose` | 可选 flag | 显示详细日志 | `false` |
+
+#### 产物
+
+```
+<target>/
+├── <adapter.skillsDir>/harness-apply-skills-main/
+│   ├── SKILL.{md|mdc}              # dispatcher skill 本体（含 frontmatter 触发词
+│   │                               #   + 末尾 ## 绑定元数据 内嵌 YAML 块，权威来源）
+│   └── references/binding.yaml     # 冗余副本（权威源在 SKILL.md 内），供工具链解析
+└── <name>-harness/                 # 仅 --clone 模式
+```
+
+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 一致；若状态文件缺失则报错。
+
+---
+
+## 架构模板
+
+### 支持的架构
+
+| `--arch` | 语言 | 规则 | 说明 |
+|----------|------|------|------|
+| `android-compose`（默认） | Kotlin + Compose | 4 条 `harness-*.mdc` | MVI + UDF + Hilt + 协程 |
+| `android-xml` | Java + XML | 5 条 `seed-*.md` | MVC + ViewBinding |
+| `cpp` | C++17 + CMake | 5 条 `seed-*.md` | 现代 C++ + CMake 规范 |
+| `web-react` | TypeScript + React | 5 条 `seed-*.md` | Hooks + 状态管理规范 |
+| `python` | Python | — | 通用 Python 模板 |
+
+> **两层叠拷合并**：`_shared/` 先落盘，`<arch>/` 随后覆盖同名文件。
+> 新增架构只需在 `templates/<new-arch>/skeleton/agent-env/rules/` 下放 3-5 条规则文件，
+> 并在 `types.ts` 与 `validate-args.ts` 各加一处枚举。
+
+### android-compose 模板详述
+
+此模板自带 4 条刚性规则和 8 个运行时技能。
+
+#### Rules —— 刚性约束层
+
+位于 `agent-env/rules/`，`.mdc` 格式，`alwaysApply: true`，Agent 会话全程加载。
+
+| 规则 | 约束域 | 核心条目 |
+|------|--------|----------|
+| `harness-compose-mandatory` | Compose 铁律 | Composable 无状态、Modifier 首参、禁组合内副作用、LazyColumn key、`remember`+`derivedStateOf`、禁 unstable 参数 |
+| `harness-mvi-layering` | MVI 分层 | 依赖方向向内、Feature 禁直达 Foundation、Reducer 纯函数、State 不可变 data class |
+| `harness-hilt-injection` | Hilt 注入 | `@HiltViewModel`+`@Inject`、`hiltViewModel()`、禁 UseCase 包装接口、Repository 接口在 Domain |
+| `harness-coroutines-scope` | 协程作用域 | 禁 `GlobalScope`、`viewModelScope`、`Dispatchers.IO`、`collectAsStateWithLifecycle`、`SharedFlow replay=0` |
+
+每条规则遵循 **"正例 → 反例 → 检测方法"** 三段式，保持 < 30 行。
+
+#### Skills —— 知识参考层
+
+位于 `agent-env/skills/`，按需触发。每个 skill 是一个目录，至少含 `SKILL.md`，可选 `references/`、`scripts/`。
+
+| Skill | 定位 | 覆盖领域 |
+|-------|------|----------|
+| `harness-android-architecture` | 合并 5 层架构 | MVI+UDF 模板、ViewModel/UseCase/Repository、多 UseCase 组合 |
+| `harness-compose-ui` | 合并 2 个 Compose UI | 状态提升、槽 API、性能优化、列表/网格 |
+| `harness-compose-state` | 新拆出 | 侧效 API 选型、StateFlow/SharedFlow 陷阱 |
+| `harness-kotlin-coroutines` | 改名适配 | 结构化并发、Flow 算子、异常处理 |
+| `harness-compose-audit` | 改名自 compose_skill-main | 9 步审计 + 评分 + 编译报告 |
+| `harness-xml-to-compose` | 改名自 migrate-xml-views | XML → Compose 10 步迁移 |
+| `harness-android-cli` | 改名自 android-cli | Android CLI 命令速查 |
+| `harness-r8-analyzer` | 改名自 r8-analyzer | R8 keep 规则冗余分析 |
+
+#### Skill 与 Rule 的引用约定
+
+每个 `SKILL.md` 末尾必须包含「必须遵守的约束规则」段落：
+
+```markdown
+## 必须遵守的约束规则
+
+> rules 引用路径：`../rules/<rule-name>.mdc`
+
+- harness-compose-mandatory
+- harness-mvi-layering
+```
+
+- 代码生成型 skill：只引用相关规则，不硬凑
+- 工具操作型 skill（CLI / R8）：写 `无（本技能为 XXX 操作，不涉及代码生成）`
+- 引用使用中立文件名（不带扩展名、不带路径），路径提示单独用 blockquote
+
+#### 命名规范
+
+| 实体 | 命名模式 | 示例 |
+|------|----------|------|
+| Rule 文件 | `harness-<domain>-<constraint>.mdc` | `harness-compose-mandatory.mdc` |
+| Skill 目录 | `harness-<domain>-<topic>/` | `harness-compose-state/` |
+| Skill 文件 | 固定 `SKILL.md` | — |
+| `harness-` 前缀 | 标识模板提供，与用户自建区分 | — |
+
+---
+
+## 常用示例
+
+```bash
+# 最简 —— 无基线，纯骨架（arch/agent 均使用默认值）
+svharness build --harness-name my-app --yes
+
+# 显式指定全部参数
+svharness build --harness-name my-app --arch android-compose --agent qoder --yes
+
+# 本地基线 + wiki 生成
+svharness build \
+  --harness-name my-app --arch android-compose --agent codechat \
+  --baseline . --generate-wiki --verbose --force
+
+# Git 远程仓库 + wiki（指定分支和文件大小限制）
+svharness build \
+  --harness-name my-app --arch android-compose --agent codechat \
+  --baseline git@github.com:user/repo.git --baseline-branch main \
+  --baseline-max-file-kb 1024 --generate-wiki --verbose --force
+
+# 内部 Git 仓库 + 自定义 API
+svharness build \
+  --harness-name my-app --arch android-compose --agent codechat \
+  --baseline git@10.133.3.88:org/repo.git --baseline-branch main \
+  --generate-wiki --wiki-base-url http://your-api.com/v1 --wiki-api-key sk-xxx \
+  --verbose --force
+
+# 仅 wiki 任务清单（默认行为，由 agent 后续撰写）
+svharness build \
+  --harness-name my-app --arch android-xml --agent qoder \
+  --baseline . --wiki-lang zh --yes
+```
+
+---
+
+## 开发指南（贡献者）
+
+### 源码目录
+
+```
+svharnessbuild/                   # 源码目录名沿用旧名（历史包名），CLI 名称已迁至 svharness
+├── bin/cli.js                    # npm bin 入口 → dist/index.js
+├── src/
+│   ├── index.ts                  # CLI 入口（commander）
+│   ├── types.ts                  # SupportedArch 枚举
+│   ├── commands/init.ts          # 4 步主管线（双模板根：_shared + <arch>）
+│   ├── core/
+│   │   ├── scaffold.ts           # scaffoldLayered: 先 _shared 再 <arch>
+│   │   ├── render-meta.ts        # renderMetaLayered: 同名 .ejs 以 <arch> 为准
+│   │   ├── state.ts              # 写 .harness-build-state.yaml
+│   │   ├── agent-injector.ts     # injectSkillsLayered
+│   │   └── next-steps.ts         # 初始化完成后的引导
+│   ├── wiki/                     # repowiki 核心模块（15 个文件）
+│   ├── adapters/                 # 各 Agent 的 skill 目录规则
+│   └── utils/                    # logger / 参数校验 / 版本读取
+├── templates/
+│   ├── _shared/                  # 跨架构公共
+│   ├── android-compose/          # Compose 规则 + 技能
+│   ├── android-xml/              # XML 规则
+│   ├── cpp/                      # C++ 规则
+│   └── web-react/                # React 规则
+└── scripts/smoke-test.ps1
+```
+
+### 版本升级
+
+> ⚠ 不要手改 `package-lock.json` 的 `version`。用 `npm version` 同步更新两个文件：
+
+```powershell
+npm version patch          # bugfix
+npm version minor          # 向后兼容新功能
+npm version 0.9.0          # 显式指定
+npm version 0.9.0 --no-git-tag-version  # 不打 git tag
+
+# 验证同步
+npm run build              # 首行应显示 svharness@<新版本>
+node -p "require('./package.json').version"
+node -p "require('./package-lock.json').version"   # 两者必须相等
+
+# 不同步时修复
+npm install                # 按 package.json 刷新 package-lock.json
+```
+
+### 本地验证
+
+```bash
+npm run build && npm pack --dry-run    # 预览包内文件
+npm pack                               # 生成 .tgz
+```
+
+验证 tgz：
+
+```powershell
+# 方式 A：npm link（开发期推荐）
+cd svharnessbuild; npm link; svharness --help
+
+# 删除
+npm unlink -g svharness
+# 或等价写法
+npm rm -g svharness
+
+# 方式 B：全局安装 tgz
+npm install -g "d:\...\svharness-<version>.tgz"; svharness --help
+
+# 方式 C：临时目录模拟
+cd $env:TEMP; mkdir test; cd test; npm init -y
+npm install -g .\svharness-<version>.tgz
+npx svharness --help
+
+# 方式 D：直接跑 CLI
+cd svharnessbuild; npm run build
+node bin\cli.js build --harness-name demo --arch android-compose --agent codechat --yes --force --verbose
+```
+
+> ⚠ **Windows**：`npx d:\...\xxx.tgz` 会被文件关联拦截，请用上述替代方式。
+
+### 发布
+
+```bash
+npm login
+npm publish --access public    # prepublishOnly 自动执行 build
+```
+
+| 分发方式 | 适用场景 | 用法 |
+|----------|----------|------|
+| **npm** | 公开发布 | `npx svharness build` |
+| **Tarball** | 小团队 / 内部试用 | `npx ./svharness-x.y.z.tgz build` |
+| **Git 仓库** | 有内网 Git | `npx github:yourorg/svharness build` |
+| **私有 Registry** | Verdaccio / Nexus | `npm publish --registry=http://内网:4873` |
+
+### 冒烟测试
+
+```powershell
+pwsh -File .\scripts\smoke-test.ps1
+```
+
+构建 TS → 临时目录 `build` → 校验文件 → `--force` 覆写验证。
+
+### 注意事项
+
+1. **shebang**：`bin/cli.js` 首行必须为 `#!/usr/bin/env node`
+2. **行尾符**：建议 `.gitattributes` 设置 `bin/*.js eol=lf`
+3. **Node 版本**：`engines.node >= 18`，兼容 18 / 20 / 22
+4. **`prepare` 脚本**：已配置，Git 仓库直装时自动编译 `dist/`
+
+---
+
+## 路线图
+
+**v0.8 —— 当前版本**
+
+- [x] 包名 `svharnessbuild` → `svharness`（保留旧 bin 别名一版本）
+- [x] 子命令 `init` → `build`（保留 `init` 隐藏别名一版本）
+- [x] 参数 `--name` → `--harness-name`（保留 `--name` 别名一版本）
+- [x] `--arch` 默认 `android-compose`、`--agent` 默认 `codechat`
+- [x] `build` —— 骨架 + 元文件 + 状态文件 + skill 注入
+- [x] 多架构模板（`android-compose` / `android-xml` / `cpp` / `web-react` / `python`）
+- [x] `_shared/` + `<arch>/` 两层叠拷合并
+- [x] 每个架构自带 3-5 条规则文件（`.mdc` 格式，`always_on` 加载）
+- [x] `apply` —— 把已构建好的 harness 绑定到目标项目（支持 `--clone` 双模式）
+- [x] 构建辅助资源统一命名（`build-skills/harness-build-skill-*`、`build-rules/harness-build-rule-*`）
+- [ ] `detach` —— 从目标项目解绑并清理 dispatcher skill
+- [ ] `doctor` —— 检查既有 harness 的健康度
+- [ ] `phase` —— 从 CLI 直接运行某个构建阶段
+- [ ] `--arch auto` —— 根据 `--baseline` 自动推断架构
+- [ ] 更多架构模板（`ios-swiftui` / `service-kotlin` / `python-fastapi` 等）
+
+欢迎对适配器与架构模板做贡献。
+
+---
+
+## License
+
+MIT

package/bin/cli.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+'use strict';
+require('../dist/index.js');

package/dist/adapters/_frontmatter.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ensureMdcFrontmatter = ensureMdcFrontmatter;
+/**
+ * Shared helper: wrap a raw markdown body with a minimal `.mdc`-style YAML
+ * frontmatter if it does not already start with `---`.
+ *
+ * Used by all adapters to keep rule files aligned with the mainstream
+ * `.mdc` convention (Cursor/Qoder/Codechat/Claude/generic).
+ */
+function ensureMdcFrontmatter(description) {
+    return (content) => {
+        if (content.startsWith('---'))
+            return content;
+        const header = [
+            '---',
+            `description: ${description}`,
+            'alwaysApply: false',
+            '---',
+            '',
+        ].join('\n');
+        return header + content;
+    };
+}

package/dist/adapters/claude-code.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.claudeCodeAdapter = void 0;
+const _frontmatter_1 = require("./_frontmatter");
+exports.claudeCodeAdapter = {
+    name: 'claude-code',
+    skillsDir: '.claude/skills',
+    skillExt: '.md',
+    rulesDir: '.claude/rules',
+    ruleExt: '.mdc',
+    ruleTransform: (0, _frontmatter_1.ensureMdcFrontmatter)('Harness build-time rule'),
+};

package/dist/adapters/codechat.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.codechatAdapter = void 0;
+const _frontmatter_1 = require("./_frontmatter");
+exports.codechatAdapter = {
+    name: 'codechat',
+    skillsDir: '.codechat/skills',
+    skillExt: '.md',
+    rulesDir: '.codechat/rules',
+    ruleExt: '.mdc',
+    ruleTransform: (0, _frontmatter_1.ensureMdcFrontmatter)('Harness build-time rule'),
+};

package/dist/adapters/cursor.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.cursorAdapter = void 0;
+const _frontmatter_1 = require("./_frontmatter");
+/**
+ * Cursor uses .cursor/rules/*.mdc with YAML frontmatter.
+ * We map our skills to rules (Cursor does not have first-class "skills" concept yet).
+ */
+exports.cursorAdapter = {
+    name: 'cursor',
+    skillsDir: '.cursor/rules',
+    skillExt: '.mdc',
+    transform: (0, _frontmatter_1.ensureMdcFrontmatter)('Harness build helper skill'),
+    // Rules go under a dedicated subfolder to avoid colliding with skills that
+    // are already written directly under `.cursor/rules/*.mdc`.
+    rulesDir: '.cursor/rules/harness-build',
+    ruleExt: '.mdc',
+    ruleTransform: (0, _frontmatter_1.ensureMdcFrontmatter)('Harness build-time rule'),
+};

package/dist/adapters/generic.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.genericAdapter = void 0;
+const _frontmatter_1 = require("./_frontmatter");
+/**
+ * Generic fallback for any non-mainstream / unknown agent.
+ * All harness artifacts (skills + rules) live under a single neutral
+ * namespace `.harness/` to avoid scattering directories across the project.
+ * Rules use `.mdc` with frontmatter to align with mainstream rule-file
+ * conventions (Cursor/Qoder/Codechat).
+ */
+exports.genericAdapter = {
+    name: 'generic',
+    skillsDir: '.harness/skills',
+    skillExt: '.md',
+    rulesDir: '.harness/rules',
+    ruleExt: '.mdc',
+    ruleTransform: (0, _frontmatter_1.ensureMdcFrontmatter)('Harness build-time rule'),
+};

package/dist/adapters/index.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getAdapter = getAdapter;
+exports.listAdapters = listAdapters;
+const codechat_1 = require("./codechat");
+const qoder_1 = require("./qoder");
+const cursor_1 = require("./cursor");
+const claude_code_1 = require("./claude-code");
+const generic_1 = require("./generic");
+const REGISTRY = {
+    codechat: codechat_1.codechatAdapter,
+    qoder: qoder_1.qoderAdapter,
+    cursor: cursor_1.cursorAdapter,
+    'claude-code': claude_code_1.claudeCodeAdapter,
+    generic: generic_1.genericAdapter,
+};
+function getAdapter(name) {
+    const adapter = REGISTRY[name];
+    if (!adapter) {
+        throw new Error(`No adapter registered for agent "${name}"`);
+    }
+    return adapter;
+}
+function listAdapters() {
+    return Object.values(REGISTRY);
+}

package/dist/adapters/qoder.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.qoderAdapter = void 0;
+const _frontmatter_1 = require("./_frontmatter");
+exports.qoderAdapter = {
+    name: 'qoder',
+    skillsDir: '.qoder/skills',
+    skillExt: '.md',
+    rulesDir: '.qoder/rules',
+    ruleExt: '.mdc',
+    ruleTransform: (0, _frontmatter_1.ensureMdcFrontmatter)('Harness build-time rule'),
+};