svharnessbuild

SDD-Driven Agent-Agnostic Coding Framework 的脚手架命令行工具。

为任何 Agent IDE（Qoder / Cursor / Claude Code 等）生成项目本地的 harness —— 一个规格驱动的知识层骨架，让 AI 协作开发有章可循。

快速开始

安装

# 从 npm 安装（发布后）
npm install -g svharnessbuild

# 或从源码安装
cd svharnessbuild && npm install && npm run build && npm link

要求 Node.js ≥ 18。

30 秒上手

# 交互式 —— 回答几个问题即可
svharnessbuild init

# 一行式 —— 跳过交互，直接生成
svharnessbuild init --name my-app --arch android-compose --agent qoder --yes

# 把构建完成的 harness 应用到其它项目（绑定式，不拷贝）
svharnessbuild 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/ 等 | init 时创建，Agent 自动加载 | rules + build-skills | | Harness 目录 | <name>-harness/ | init 创建骨架 → Agent 逐步填充 | specs / assets / agent-env / tasks |

目录结构

执行 svharnessbuild init 后生成：

<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- 专属于 构建期（init / orchestrator 驱动 harness 骨架填充），与运行期 skill（harness-<domain>-<topic>、如 harness-compose-ui）及 apply 注入的 harness-apply-skills-main dispatcher 明确区分。
• 文件内部 frontmatter name、一级 heading、交叉引用必须与文件名保持一致。
• 新增同类资源时沿用此三段式，禁止回退到两段式（如旧名 harness-orchestrator / harness-build-orchestrator-flow 已废弃）。

构建阶段

init 只生成骨架。各阶段的实际内容由 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 不得自行生成占位文件。

命令参考

init —— 初始化 harness

交互式

svharnessbuild init

依次提问：--name / --arch / --agent / --baseline（可选）。

非交互（CI / 脚本）

svharnessbuild init \
  --name my-app \
  --arch android-compose \
  --agent codechat \
  --baseline ../my-baseline-repo \
  --yes

全部参数

| 参数 | 说明 | 默认值 | |------|------|--------| | --name | 项目名，生成 <name>-harness/ 目录 | 交互输入 | | --arch | 架构模板 | android-compose | | --agent | 目标 Agent IDE | generic | | --baseline | 基线来源：本地目录 或 git 仓库 URL | — | | --baseline-branch | git 基线的分支名（仅 git 模式） | main | | --baseline-max-file-kb | 基线拷贝单文件大小上限（KB） | 1024 | | --force | 覆写已存在的 harness 目录 | — | | --yes / -y | 跳过所有提示，采用默认值 | — | | --verbose | 打印每个生成文件 | — |

Wiki 参数

| 参数 | 说明 | 默认值 | |------|------|--------| | --generate-wiki | init 时直接逐页生成完整 wiki（与 --wiki-tasks-only 互斥） | — | | --wiki-tasks-only | 仅生成 wiki outline + TASKS.md（兼容保留） | 默认行为 | | --wiki-lang | wiki 语言 | zh | | --wiki-model | LLM 模型名 | Qwen3.6-27B | | --wiki-base-url | OpenAI 兼容 API 地址 | http://model-api.desaysv.com/v1 | | --wiki-api-key | API Key | 环境变量 OPENAI_API_KEY | | --wiki-source | wiki 扫描的仓库根路径 | <target>/assets/baseline/code/ |

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/（通过 init + orchestrator 构建完成的知识层）以最小侵入方式应用到任意目标项目：向该项目的 Agent IDE skill 目录注入一个 dispatcher skill（harness-apply-skills-main），由它在运行期从 skill 正文内嵌的 ## 绑定元数据 块定位 harness 并路由到具体能力。references/binding.yaml 作为冗余副本同时写入，仅供 svharnessbuild 自身工具链（status / detach / re-apply 检测）解析，运行时 dispatcher 不读它。

# bind-only（默认）—— 仅注入 dispatcher skill，harness 保留在原位置
svharnessbuild apply --harness ../my-app-harness --target ./to-apply-project

# clone —— 把整个 harness 完整拷贝到目标项目根下，binding.yaml 指向本地副本
svharnessbuild 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> | 目标项目根目录 | 当前工作目录 | | --agent <agent> | 目标 Agent：codechat / qoder / cursor / claude-code / generic | 从 <harness>/.harness-build-state.yaml 读取 | | --clone | 完整拷贝 harness 到目标项目根下 | 不拷贝（bind-only） | | --force | 覆盖已存在的 dispatcher skill 目录（clone 模式下同时覆盖克隆目标） | — | | -y, --yes | 跳过交互确认 | — | | --verbose | 显示详细日志 | — |

产物

<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 只是同字段的冗余副本。字段示例：

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: [email protected]

• 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 末尾必须包含「必须遵守的约束规则」段落：

## 必须遵守的约束规则

> 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- 前缀 | 标识模板提供，与用户自建区分 | — |

常用示例

# 最简 —— 无基线，纯骨架
svharnessbuild init --name my-app --arch android-compose --agent qoder --yes

# 本地基线 + wiki 生成
svharnessbuild init \
  --name my-app --arch android-compose --agent codechat \
  --baseline . --generate-wiki --verbose --force

# Git 远程仓库 + wiki（指定分支和文件大小限制）
svharnessbuild init \
  --name my-app --arch android-compose --agent codechat \
  --baseline [email protected]:user/repo.git --baseline-branch main \
  --baseline-max-file-kb 1024 --generate-wiki --verbose --force

# 内部 Git 仓库 + 自定义 API
svharnessbuild init \
  --name my-app --arch android-compose --agent codechat \
  --baseline [email protected]: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 后续撰写）
svharnessbuild init \
  --name my-app --arch android-xml --agent qoder \
  --baseline . --wiki-lang zh --yes

开发指南（贡献者）

源码目录

svharnessbuild/
├── 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 同步更新两个文件：

npm version patch          # bugfix
npm version minor          # 向后兼容新功能
npm version 0.3.0          # 显式指定
npm version 0.3.0 --no-git-tag-version  # 不打 git tag

# 验证同步
npm run build              # 首行应显示 svharnessbuild@<新版本>
node -p "require('./package.json').version"
node -p "require('./package-lock.json').version"   # 两者必须相等

# 不同步时修复
npm install                # 按 package.json 刷新 package-lock.json

本地验证

npm run build && npm pack --dry-run    # 预览包内文件
npm pack                               # 生成 .tgz

验证 tgz：

# 方式 A：npm link（开发期推荐）
cd svharnessbuild; npm link; svharnessbuild --help

# 删除
npm unlink -g svharnessbuild
# 或等价写法
npm rm -g svharnessbuild 

# 方式 B：全局安装 tgz
npm install -g "d:\...\svharnessbuild-<version>.tgz"; svharnessbuild --help

# 方式 C：临时目录模拟
cd $env:TEMP; mkdir test; cd test; npm init -y
npm install -g .\svharnessbuild-<version>.tgz
npx svharnessbuild --help

# 方式 D：直接跑 CLI
cd svharnessbuild; npm run build
node bin\cli.js init --name demo --arch android-compose --agent qoder --yes --force --verbose

⚠ Windows：npx d:\...\xxx.tgz 会被文件关联拦截，请用上述替代方式。

发布

npm login
npm publish --access public    # prepublishOnly 自动执行 build

| 分发方式 | 适用场景 | 用法 | |----------|----------|------| | npm | 公开发布 | npx svharnessbuild init | | Tarball | 小团队 / 内部试用 | npx ./svharnessbuild-x.y.z.tgz init | | Git 仓库 | 有内网 Git | npx github:yourorg/svharnessbuild init | | 私有 Registry | Verdaccio / Nexus | npm publish --registry=http://内网:4873 |

冒烟测试

pwsh -File .\scripts\smoke-test.ps1

构建 TS → 临时目录 init → 校验文件 → --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.3 —— 当前版本

• [x] init —— 骨架 + 元文件 + 状态文件 + 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 —— 根据 --source 自动推断架构
• [ ] 更多架构模板（ios-swiftui / service-kotlin / python-fastapi 等）

欢迎对适配器与架构模板做贡献。

License

MIT