svharness 0.8.0 → 0.13.2

package/templates/_shared/build-skills/harness-build-skill-wiki-writer.md

@@ -2,34 +2,34 @@
 name: harness-build-skill-wiki-writer
 description: >
   逐页撰写 baseline wiki 正文。读取 state 中 `tasks_file` 指向的任务清单与 structure.xml，
-  基于 assets/baseline/code/ 下的源码快照产出每一页 Markdown。当用户说"生成 baseline wiki 正文"、
+  基于 baseline/code/ 下的源码快照产出每一页 Markdown。当用户说"生成 baseline wiki 正文"、
   "按 TASKS.md 逐页生成 baseline wiki"、"继续写 wiki 下一页"，或由 harness-build-skill-orchestrator
-  在阶段 P1_wiki 委派时触发。
+  在阶段 S10_wiki 委派时触发。
 ---
 
 # harness-build-skill-wiki-writer（baseline wiki 正文撰写）
 
-你只做一件事：**按 `__HARNESS_ROOT__.harness-build-state.yaml` 中 `P1_wiki.tasks_file` 指向的任务清单，
-一页一页地，基于 `__HARNESS_ROOT__assets/baseline/code/` 下的真实源码，写成 Markdown**。
-规则抽取、快照选样、skills/tasks 索引不是你的职责（那是 harness-build-skill-knowledge-builder）。
+你只做一件事：**按 `__HARNESS_ROOT__.harness-build-state.yaml` 中 `S10_wiki.tasks_file` 指向的任务清单，
+一页一页地，基于 `__HARNESS_ROOT__baseline/code/` 下的真实源码，写成 Markdown**。
+references intake、agent-env 合并、skills/tasks 索引不是你的职责（分别由 harness-build-skill-references-intake、harness-build-skill-agent-env-merge、harness-build-skill-knowledge-builder 负责）。
 
 ## 输入
 
-- `__HARNESS_ROOT__.harness-build-state.yaml` → `P1_wiki.tasks_file` —— 任务清单路径（通常 `__HARNESS_ROOT__assets/baseline/wiki/TASKS.md`）；
+- `__HARNESS_ROOT__.harness-build-state.yaml` → `S10_wiki.tasks_file` —— 任务清单路径（通常 `__HARNESS_ROOT__baseline/wiki/TASKS.md`）；
   复选框形态，`[ ]` 待办、`[x]` 已完成
-- `__HARNESS_ROOT__assets/baseline/wiki/structure.xml` —— outline 权威来源；title / sectionFolder / parentSection 以此为准
-- `__HARNESS_ROOT__assets/baseline/code/` —— **唯一允许引用**的源码根；所有链接与行号引用都相对它
+- `__HARNESS_ROOT__baseline/wiki/structure.xml` —— outline 权威来源；title / sectionFolder / parentSection 以此为准
+- `__HARNESS_ROOT__baseline/code/` —— **唯一允许引用**的源码根；所有链接与行号引用都相对它
 
 ## 算法
 
 1. 读取 `TASKS.md`，找到第一条 `[ ]` 任务。若全部 `[x]`：
-   - 汇报"P1_wiki 可以标记 DONE"，并请 harness-build-skill-orchestrator 以最小补丁更新
-     `__HARNESS_ROOT__.harness-build-state.yaml` 中 `P1_wiki.status: DONE`，然后退出。
-2. 取该任务的 `Output` 路径（相对 `__HARNESS_ROOT__assets/baseline/wiki/`）、`Title`、`Section`、
+   - 汇报"S10_wiki 可以标记 DONE"，并请 harness-build-skill-orchestrator 以最小补丁更新
+     `__HARNESS_ROOT__.harness-build-state.yaml` 中 `S10_wiki.status: DONE`，然后退出。
+2. 取该任务的 `Output` 路径（相对 `__HARNESS_ROOT__baseline/wiki/`）、`Title`、`Section`、
    `Parent section id`（如有）、`Description`、`Relevant files`。
-3. 打开每个 Relevant file（位于 `__HARNESS_ROOT__assets/baseline/code/<repo-relative>`），读取真实内容；
-   必要时使用 grep/search_symbol 等工具补足上下文，但**不得离开 `__HARNESS_ROOT__assets/baseline/code/`**。
-4. 撰写 Markdown，写入 `__HARNESS_ROOT__assets/baseline/wiki/<Output>`。
+3. 打开每个 Relevant file（位于 `__HARNESS_ROOT__baseline/code/<repo-relative>`），读取真实内容；
+   必要时使用 grep/search_symbol 等工具补足上下文，但**不得离开 `__HARNESS_ROOT__baseline/code/`**。
+4. 撰写 Markdown，写入 `__HARNESS_ROOT__baseline/wiki/<Output>`。
 5. 写完后最小补丁式修改 `TASKS.md`，把该任务的 `[ ]` 改为 `[x]`（不得重排任务顺序、不得删除其他行）。
 6. 默认单步询问是否继续下一页。如果用户说"批量"、"全部继续"、"run through"，则连续处理至清单尾。
 
@@ -38,27 +38,27 @@ description: >
 - **H1** 必须与 task `Title` 完全一致。
 - **简介段** 后若后续有 2 个及以上的 `##` 章节，插入锚点式 TOC。
 - **Mermaid** 使用 `graph TD` 或 `sequenceDiagram`，不使用 classDef / style / 颜色。
-- **引用源码** 必须指向 `__HARNESS_ROOT__assets/baseline/code/`。允许两种书写方式（可混用）：
-  - 行内链接：`[Foo.java:10-30](../../../assets/baseline/code/<repo-relative>/Foo.java#L10-L30)`
+- **引用源码** 必须指向 `__HARNESS_ROOT__baseline/code/`。允许两种书写方式（可混用）：
+  - 行内链接：`[Foo.java:10-30](../../baseline/code/<repo-relative>/Foo.java#L10-L30)`
   - Sources 行：`Sources: <repo-relative>/Foo.java:10-30, <repo-relative>/Bar.kt:5-8`
-  `<repo-relative>` 是**相对 `__HARNESS_ROOT__assets/baseline/code/` 的路径**，既不是仓库原始绝对路径，
+  `<repo-relative>` 是**相对 `__HARNESS_ROOT__baseline/code/` 的路径**，既不是仓库原始绝对路径，
   也不是 wiki md 文件的相对路径。行号采用 `start-end`（闭区间）。
 - 禁止粘贴大段代码：单个 code block ≤ 40 行；必要时用省略号 `// ...` 裁剪。
 - 所有中文段落使用中文标点；字段名、类名、路径保留英文不译。
 
 ## 产出
 
-- `__HARNESS_ROOT__assets/baseline/wiki/<lang>/<section>/<stem>.md` —— 每个 task 一份
+- `__HARNESS_ROOT__baseline/wiki/<lang>/<section>/<stem>.md` —— 每个 task 一份
 - 更新后的 `TASKS.md` —— 状态位从 `[ ]` 推进为 `[x]`，其他内容不动
 
 ## 守则（不得违反）
 
-- **不得凭空编造代码或结论**：任何结论都必须可追溯到 `__HARNESS_ROOT__assets/baseline/code/` 下的真实文件。
+- **不得凭空编造代码或结论**：任何结论都必须可追溯到 `__HARNESS_ROOT__baseline/code/` 下的真实文件。
 - **不得修改 `structure.xml`** 或 `TASKS.md` 中 task 的 `Output / Section / Parent section id / Relevant files` 字段。
 - **不得整文件重写 `TASKS.md`**：只做最小补丁（复选框 `[ ]` → `[x]`）。
-- **不得在本 skill 内执行规则抽取、快照选样、skill/task 索引**（那是 harness-build-skill-knowledge-builder 的 P5/P6）。
-- **不得使用不在 `__HARNESS_ROOT__assets/baseline/code/` 下的源码路径**作为 Sources 引用。
-- 全部 wiki 完成后，由 harness-build-skill-orchestrator（不是本 skill）把 `P1_wiki` 标记 DONE。
+- **不得在本 skill 内执行 references intake、agent-env 合并、skill/task 索引**（分别由 `harness-build-skill-references-intake`、`harness-build-skill-agent-env-merge`、`harness-build-skill-knowledge-builder` 负责）。
+- **不得使用不在 `__HARNESS_ROOT__baseline/code/` 下的源码路径**作为 Sources 引用。
+- 全部 wiki 完成后，由 harness-build-skill-orchestrator（不是本 skill）把 `S10_wiki` 标记 DONE。
 - 所有面向用户的说明使用中文；字段名、路径、类名保留英文。
 - **必须以表单方式**与用户交互确认，禁止仅以纯文本输出后自行继续。
 - **所有 wiki 正文段落必须使用中文**（代码、类名、路径等保留英文）。
@@ -68,10 +68,10 @@ description: >
 本 skill 执行前必须加载并严格遵循（文件位于当前 agent 的 rules 目录，具体路径/扩展名
 随 agent 可能为 `.md` 或 `.mdc`）：
 
-- `harness-build-rule-orchestrator-flow` — 本 skill 仅服务 P1_wiki，禁止跨阶段工作。
+- `harness-build-rule-orchestrator-flow` — 本 skill 仅服务 S10_wiki，禁止跨阶段工作。
 - `harness-build-rule-agent-agnostic` — wiki 正文严禁硬编码具体 agent 名或其私有指令语法。
 - `harness-build-rule-memory-write` — 撰写中如识别到可复用经验，按 inbox → categories 写入。
 - `harness-build-rule-chinese-only` — 所有产出内容必须使用中文。
 - `harness-build-rule-user-interaction` — 用户交互铁律：表单确认、禁止擅自修改。
 
-若规则文件缺失，停止工作并提示用户重新运行 `svharnessbuild init`。
+若规则文件缺失，停止工作并提示用户重新运行 `svharness build`。

package/templates/_shared/build-skills/harness-build-skills-main.md

@@ -0,0 +1,83 @@
+---
+name: harness-build-skills-main
+description: >
+  Harness **构建期**二级调度：从本 skill 正文末尾的 `## 绑定元数据` 解析 `harness_root_rel`，
+  读取 `__HARNESS_ROOT__AGENTS_BUILD.md` 与 `__HARNESS_ROOT__.harness-build-state.yaml`，
+  加载项目根下 `__HARNESS_BUILD_RULES_DIR__` 的构建规则，再按语义把任务路由到下列 **harness-build**
+  子 skill。当用户说"按 harness-build-skills-main 开始构建"、"harness-build 总清单"、
+  "载入整个 harness-build"、"从清单调度 harness 构建" 时触发。
+---
+
+# harness-build-skills-main（harness-build 总清单 / 二级调度）
+
+你是 **harness SDD 构建工作流** 的入口调度器。用户要进行 harness 脚手架内的规格 / wiki / rules /
+skills 等**构建阶段**工作时，你不直接越级写产物，而是先完成：**绑定解析 → 规则装载 →
+子 skill 路由表建立 → 再委派**。
+
+> 本 skill 由 `svharness build` 注入到 `__HARNESS_BUILD_SKILLS_DIR__/`。harness 目录位于
+> 项目根下的 `harness_root_rel`（见文末 YAML）。所有对 harness 内文件的引用必须基于该相对路径，
+> 禁止假设 harness 与当前工作目录的其它相对关系。
+
+## 输入
+
+- **本 skill 正文末尾 `## 绑定元数据` YAML 块**（权威）：
+  - `harness_root_rel` —— 相对项目根目录的 harness 路径（形如 `./my-app-harness/`）
+  - `harness_name` —— harness 短名（目录名去掉 `-harness` 后缀）
+  - `arch` —— 架构模板 id
+  - `agent` —— 注入目标 Agent 标识
+  - `build_rules_dir` —— 构建规则已注入的相对路径（可能为空）
+  - `build_skills_dir` —— 本套 build skill 已注入的相对路径
+  - `generated_at` / `generated_by` —— 生成时间与工具版本
+- `__HARNESS_ROOT__AGENTS_BUILD.md` —— Agent 接入 harness 的必读步骤清单
+- `__HARNESS_ROOT__.harness-build-state.yaml` —— 当前阶段与 `next_action`
+- `__HARNESS_ROOT__harness.yaml` —— 清单与版本
+
+## harness-build 子 skill 路由表（按需深读）
+
+| id | 职责 | 典型触发 |
+|----|------|----------|
+| `harness-build-skill-orchestrator` | 读取状态机、输出状态卡片、阶段推进、更新 `next_action` | 「开始构建 harness」「继续 harness」「harness 进度」 |
+| `harness-build-skill-spec-builder` | raw → requirements YAML → specs YAML（schema 校验） | S40 / S50 阶段 |
+| `harness-build-skill-references-intake` | references 转换与结构化索引 | S60 阶段 |
+| `harness-build-skill-agent-env-merge` | baseline 自动提取确认 + extra-skills/rules 合并写入 | S61 / S65 阶段 |
+| `harness-build-skill-knowledge-builder` | baseline 样本 + runtime skills/tasks 索引 | S10(子任务) / S70 阶段 |
+| `harness-build-skill-wiki-writer` | 按 `baseline/wiki/TASKS.md` 逐页撰写 wiki | S10_wiki PENDING |
+
+以上子 skill 的完整正文位于 `__HARNESS_BUILD_SKILLS_DIR__/<id>/` 下（文件名随 Agent 为 `SKILL.md` 或 `SKILL.mdc`）。
+
+## 算法
+
+1. **加载绑定**：解析文末「绑定元数据」标题下 fenced YAML 代码块。若失败或缺少
+   `harness_root_rel`，停止并提示用户重新运行 `svharness build`（或检查 skill 是否被手工破坏）。
+
+2. **校验 harness 根**：确认 `harness_root_rel` 指向的目录存在，且内含
+   `.harness-build-state.yaml` 与 `AGENTS_BUILD.md`（或给出明确缺失项）。
+
+3. **装载构建规则（强约束）**：若 `build_rules_dir` 非空，枚举并阅读
+   `<项目根>/<build_rules_dir>/` 下由 `svharness build` 注入的 harness 构建规则（`always_on` 必须全部遵守）。
+   规则与 `AGENTS_BUILD.md` 冲突时以**规则文件**为准。
+
+4. **建立会话路由**：根据用户意图在「路由表」中选择 1 个入口子 skill：
+   - 未指定具体子任务 / 首次进入构建 → **优先**委派给 `harness-build-skill-orchestrator`
+   - 用户明确只做 wiki 页 → `harness-build-skill-wiki-writer`
+   - 用户明确只做 spec / requirements → `harness-build-skill-spec-builder`
+   - 用户明确处理 references intake → `harness-build-skill-references-intake`
+   - 用户明确处理 extra-skills/rules 合并 → `harness-build-skill-agent-env-merge`
+   - 用户明确补充 S70 runtime assets / baseline 样本 → `harness-build-skill-knowledge-builder`
+
+5. **执行守则**：遵守各子 skill 与 `agent-env/rules/` 中的交互与输出约定；不得跳过
+   orchestrator 所定义的阶段红线（见 `harness-build-rule-orchestrator-flow`）。
+
+6. **面向用户的说明使用中文**；字段名、路径、CMD ID 等保留英文。
+
+## 守则（不得违反）
+
+- **不得跳过本 skill 内嵌的绑定元数据**去猜测 harness 路径。
+- **不得把 AGENTS_BUILD.md 中的指引当作可违背的软建议**；其中「先读 specs / rules」与状态机阶段准入仍必须遵守。
+- **不得将 apply 期的 `harness-apply-skills-main` 与 build 期的本子 skill 混用**：apply 面向目标业务项目绑定；本 skill 仅服务 harness 目录内的 SDD 构建流水线。
+
+## 绑定元数据（权威来源，由 svharness build 生成，请勿手工编辑）
+
+```yaml
+{{BINDING_YAML_BLOCK}}
+```

package/templates/_shared/meta/AGENTS_APPLY.md.ejs

@@ -0,0 +1,139 @@
+# AGENTS_APPLY.md（harness 应用指南）
+
+> 本文件是 AI 编码 Agent **应用 harness 知识层**到目标项目时的入口。
+> 与 `AGENTS_BUILD.md`（构建指南）互补：`AGENTS_BUILD.md` 驱动 harness 本体的构建与演进，
+> **本文件驱动 harness 知识向目标项目的落地执行**。
+>
+> 如果你是通过 `svharnessbuild apply` 注入的 `harness-apply-skills-main` skill
+> 进入的，请先执行该 skill 的调度流程，再参照本文件的守则补充上下文。
+
+## 1. 前置条件
+
+在开始开发前，确认以下状态：
+
+1. `harness.yaml` —— 清单文件，确认 `name`、`arch`、`agent` 与目标项目一致
+2. `.harness-build-state.yaml` —— 构建状态，确认关键阶段（`S00_bootstrap` ~ `S50_generate_specs`）至少为 `DONE`
+3. `agent-env/rules/` —— 存在 `.mdc` / `.md` 规则文件（强约束）
+4. `agent-env/skills/` —— 存在子 skill 目录（可选能力）
+5. `specs/` —— 存在功能规格（若 `bootstrap_mode: true`，规格仍在草稿阶段，需人工确认）
+
+> 若 harness 尚未完成构建（如 `S70_runtime_assets` 仍为 `PENDING`），
+> 建议先回到 harness 本体执行构建流程，而非直接应用。
+
+## 2. 加载约束与能力
+
+### 2.1 强约束（必须遵守）
+
+枚举并读取 `agent-env/rules/` 下所有规则文件：
+
+- `always_on` 规则 —— **每次任务都必须遵守**，不得跳过
+- `model_decision` 规则 —— 按本次任务语义挑选适用规则
+
+规则冲突时以 `always_on` 规则为准。典型约束包括但不限于：
+
+- `harness-compose-mandatory.mdc` —— Compose UI 强制规范
+- `harness-mvi-layering.mdc` —— MVI 分层约束
+- `harness-hilt-injection.mdc` —— 依赖注入规范
+- `harness-coroutines-scope.mdc` —— 协程作用域规范
+
+### 2.2 子能力（按需调用）
+
+枚举 `agent-env/skills/*/SKILL.md`，提取 `name` + `description` 建立路由表。
+不要整目录朗读，按需要再深读。典型子能力包括：
+
+- `harness-android-architecture` —— Android 架构模板
+- `harness-compose-ui` —— Compose UI 组件编写
+- `harness-compose-state` —— 状态管理
+- `harness-xml-to-compose` —— XML → Compose 迁移
+- `harness-kotlin-coroutines` —— 协程最佳实践
+- `harness-android-cli` —— ADB / Gradle 命令
+
+## 3. 开发工作流
+
+```
+用户需求 → 加载约束 → 语义路由 → 查阅基线/规格 → 编码 → 校验 → 交付
+```
+
+### 3.1 理解需求
+
+- 明确功能边界：是新增、修改还是重构？
+- 若存在 `specs/` 中对应的规格文件，**必须先对齐 schema** 再编码
+- 若需求与现有规格冲突，先提规格变更，再写代码
+
+### 3.2 查阅基线与规格
+
+按需参考以下目录（均在 harness 根下）：
+
+| 目录 | 用途 | 读写 |
+|------|------|------|
+| `baseline/wiki/` | 项目知识摘要，优先建立上下文 | 只读 |
+| `baseline/code/` | 权威参考实现 | 只读 |
+| `specs/signals/` | 信号/协议规格 | 只读 |
+| `specs/ui/` | UI 规格 | 只读 |
+| `specs/behavior/` | 行为规格 | 只读 |
+| `specs/interfaces/` | 接口规格 | 只读 |
+| `tasks/templates/` | 任务模板 | 只读 |
+
+> **禁止引用 `baseline/code/` 之外的源码**作为"参考实现"。
+
+### 3.3 编码执行
+
+- **所有代码写在目标项目下**，不得修改 harness 目录内的文件
+- 引用 harness 文件时使用相对路径
+- 严格遵守 `agent-env/rules/` 中的所有约束
+- 产出必须同时满足 `specs/`（做什么）与 `agent-env/rules/`（怎么做）
+
+### 3.4 交付校验
+
+- 涉及 specs 的任务，产物必须通过 `specs/*/schema.json` 校验
+- 代码改动不得违反 `agent-env/rules/` 中的规则
+- 在 PR 描述中记录每一条外部假设
+
+## 4. 记忆沉淀
+
+若本次开发产生了可复用经验：
+
+- 新经验放入 `agent-env/memory/inbox/`（待审核）
+- 经人工审核后转入 `agent-env/memory/categories/`
+- 不确定时停住询问，不得擅自归档
+
+## 5. 守则（不得违反）
+
+- **不得修改 harness 目录下的文件**（rules / skills / specs / baseline / VERSION）
+  harness 是只读知识源，演进由构建流程负责
+- **不得绕过绑定元数据**猜测 harness 路径；路径错误须让用户重新绑定
+- **不得把 `always_on` 规则当成"建议"**——它们是硬约束
+- **不得引用 `baseline/code/` 之外的源码**作为参考实现
+- 所有面向用户的说明使用**中文**；字段名、类名、路径保留英文
+- 多个子 skill 有冲突结论时，显式告知用户并请其裁决
+
+## 6. 典型应用示例
+
+### 示例 1：新增设置项页面
+
+```
+用户：基于 harness 新增"显示设置"Fragment
+Agent：
+  1. 加载 harness-compose-mandatory.mdc + harness-mvi-layering.mdc
+  2. 路由到 harness-compose-ui skill
+  3. 查阅 specs/ui/ 中是否有显示设置相关规格
+  4. 参考 baseline/code/ 中的 Fragment 样本
+  5. 在目标项目 src/ 下编写 Compose UI + ViewModel + Repository
+  6. 校验规格一致性
+```
+
+### 示例 2：新增协议信号
+
+```
+用户：按 harness 规范实现 CMDID 0xA3 信号解析
+Agent：
+  1. 加载 harness-mvi-layering.mdc
+  2. 查阅 specs/signals/ 中的信号规格
+  3. 参考 baseline/code/ 中的现有信号解析代码
+  4. 编写信号解析 + 状态层
+  5. 通过 specs/signals/schema.json 校验
+```
+
+---
+
+架构: **<%= arch %>**　　Agent: **<%= agent %>**　　生成时间: <%= createdAt %>

package/templates/_shared/meta/{AGENTS.md.ejs → AGENTS_BUILD.md.ejs}

@@ -1,6 +1,6 @@
-# AGENTS.md
+# AGENTS_BUILD.md
 
-> 本文件是任何 AI 编码 Agent 接入 **<%= name %>** 项目的入口。
+> 本文件是任何 AI 编码 Agent 接入 **<%= name %>-harness** 项目的入口。
 > 请**按顺序**完成以下步骤，不要跳步。
 
 ## 1. 加载上下文（只读）
@@ -11,21 +11,23 @@
 2. `.harness-build-state.yaml` —— 当前构建阶段与待办动作
 3. `specs/**/*.yaml` —— 权威的「做什么」（功能契约，唯一事实来源）
 4. `agent-env/rules/*.mdc` —— 架构层面的「怎么做」（不得违反的约束）
-5. `assets/baseline/wiki/**/*.md` —— 基线源码知识快照（指引，不是契约）
+5. `baseline/wiki/**/*.md` —— 基线源码知识快照（指引，不是契约）
 
 ## 2. 查看状态，选择下一步
 
 - 打开 `.harness-build-state.yaml`
 - 识别 `current_phase`
 - 优先调用 `next_action` 中建议的 skill
-- `P1_wiki` 若存在：读其 `mode` / `source` / `tasks_file` 字段判断 wiki 当前形态，
+- `S10_wiki` 若存在：读其 `mode` / `source` / `tasks_file` 字段判断 wiki 当前形态，
   详见 harness-build-skill-orchestrator / harness-build-skill-wiki-writer skill
 
 若你所在的 Agent IDE 支持 skill 触发，请使用下列构建辅助 skill：
 
 - **harness-build-skill-orchestrator** —— 驱动整体构建流程
 - **harness-build-skill-spec-builder** —— raw → requirements → specs
-- **harness-build-skill-knowledge-builder** —— baseline/code 样本 / rules / skills & tasks
+- **harness-build-skill-references-intake** —— S60 references 转换与结构化索引
+- **harness-build-skill-agent-env-merge** —— S61 baseline 自动提取确认 + S65 合并写入
+- **harness-build-skill-knowledge-builder** —— S10 baseline/code 样本 + S70 skills & tasks
 - **harness-build-skill-wiki-writer** —— 按 TASKS.md 逐页撰写 baseline wiki 正文
 
 ## 3. 产出

package/templates/_shared/meta/CHANGELOG.md.ejs

@@ -6,10 +6,10 @@
 
 ### Added
 - 由 svharnessbuild v<%= version %> 初次生成骨架（架构：<%= arch %>，Agent：<%= agent %>）。
-- 建立分层目录结构：`specs/` / `assets/` / `agent-env/` / `tasks/` / `commands/`。
+- 建立分层目录结构：`specs/` / `requirements/` / `references/` / `baseline/` / `agent-env/` / `tasks/` / `commands/`。
 - 建立四层 spec 的 JSON Schema（signals / ui / behavior / interfaces）。
-- 在 Agent 工作目录中注入构建辅助 skill：harness-build-skill-orchestrator、harness-build-skill-spec-builder、harness-build-skill-knowledge-builder。
-- 初始化 `.harness-build-state.yaml`，除 `P-1_skeleton` 为 DONE 外，其余阶段均为 PENDING。
+- 在 Agent 工作目录中注入构建辅助 skill：harness-build-skill-orchestrator、harness-build-skill-spec-builder、harness-build-skill-references-intake、harness-build-skill-agent-env-merge、harness-build-skill-knowledge-builder。
+- 初始化 `.harness-build-state.yaml`，除 `S00_bootstrap` 为 DONE 外，其余阶段均为 PENDING。
 <% if (sourcePath) { -%>
 - 已登记基线源码路径：`<%= sourcePath %>`。
 <% } -%>

package/templates/_shared/meta/README.md.ejs

@@ -11,7 +11,7 @@
 | 层 | 职责 |
 |----|------|
 | `specs/` | 权威的「做什么」 —— signals / UI / behavior / interfaces（通过 schema 校验的 YAML） |
-| `assets/` | 输入与基线 —— `raw/`、`requirements/`、`baseline/{code,wiki}/` |
+| `requirements/` + `references/` | 输入与基线 —— `requirements/{raw,md,yaml}`、`references/{raw,md,yaml}`、`baseline/{code,wiki}/` |
 | `agent-env/` | Agent 运行时环境 —— `rules/`、`skills/`、`tools/`、`memory/{categories,inbox}/` |
 | `tasks/` | 声明式 task 模板（`templates/`），通过路径引用 specs / rules / skills |
 | `commands/` | 命令式工作流 —— `install/`（一次性初始化）、`update/`（日常治理） |
@@ -24,14 +24,16 @@
 
 注入的 **harness-build-skill-orchestrator** skill 会读取 `.harness-build-state.yaml`，并逐步引导你走完下列流程：
 
-1. **P1 raw** —— 把原始需求文档放入 `assets/raw/`
-2. **P2 requirements** —— Agent 将其结构化为 `assets/requirements/*.yaml`
-3. **P3 specs** —— Agent 在 `specs/*/` 下生成 YAML 并通过 schema 校验
-4. **P4 baseline_wiki** —— Agent 汇总代码知识到 `assets/baseline/wiki/` 并拷贝 ~20 个关键参考文件到 `assets/baseline/code/`
-5. **P5 rules** —— 人工填充架构约束到 `agent-env/rules/`（Agent 起草，人工审核）
-6. **P6 skills_tasks** —— 项目专属的运行期 skill 与 task 模板
-7. **P7 memory** —— Agent 播种初始 memory 分类
-8. **P-Final** —— `svharnessbuild seal` 将 `bootstrap_mode` 翻转为 false
+1. **S20_collect_inputs** —— 添加相关文件（`requirements/raw/`、`references/raw/`，并确认是否有额外运行期资源；可通过 `--extra-skills` 单入口混放提供）
+2. **S30_convert_docs** —— 非 Markdown 原始文档统一转换到对应 `md/` 目录
+3. **S40_extract_requirements** —— Agent 将需求结构化为 `requirements/yaml/`
+4. **S50_generate_specs** —— Agent 在 `specs/*/` 下生成 YAML 并通过 schema 校验
+5. **S60_process_references** —— 处理 references（`svharness convert` + 结构化索引 + 表单确认落地）
+6. **S61_confirm_baseline_extraction** —— 确认是否自动从 baseline 提取 skills/rules（表单确认）
+7. **S65_customize_agent_env** —— 对 extra-skills/extra-rules（及已确认启用的 baseline 提取候选）执行合并写入；来源可来自 `_incoming/manifest.yaml`；冲突时"建议 → 确认 → 写入"
+8. **S70_runtime_assets** —— 产出运行期 skills 与 tasks（skills 是能力积木，tasks 是流程模板）
+9. **S80_seed_memory** —— Agent 播种初始 memory 分类
+10. **S90_finalize** —— `svharnessbuild seal` 将 `bootstrap_mode` 翻转为 false
 
 ## 常用命令
 

package/templates/_shared/meta/harness.yaml.ejs

@@ -18,18 +18,39 @@ specs:
     - { name: behavior,   schema: specs/behavior/schema.json }
     - { name: interfaces, schema: specs/interfaces/schema.json }
 
-# 输入与基线素材。
-assets:
-  raw: assets/raw/                        # 原始未加工需求文档
-  requirements: assets/requirements/      # 条目化后的结构化需求
-  baseline:
-    code: assets/baseline/code/           # 基线代码快照（参考样本）
-    wiki: assets/baseline/wiki/           # 基线工程 wiki
+# 输入与基线素材（顶层目录，不再嵌套在 assets/ 下）。
+requirements:                            # 正式需求（参与条目化）
+  raw: requirements/raw/                 #   S20_collect_inputs 用户入口
+  md: requirements/md/                   #   convert 产物
+  yaml: requirements/yaml/               #   S40 条目化产出
+  # requirements 输入路径（可选）：可记录外部需求文档来源（文件或目录）。
+<% if (requirementsPath) { -%>
+  source: "<%= requirementsPath %>"
+<% } else { -%>
+  source: null
+<% } -%>
+references:                              # 参考资料（不参与条目化）
+  raw: references/raw/
+  md: references/md/
+  yaml: references/yaml/
+  # references 输入路径（可选）：可记录外部参考资料来源（文件或目录）。
+<% if (referencesPath) { -%>
+  source: "<%= referencesPath %>"
+<% } else { -%>
+  source: null
+<% } -%>
+baseline:
+  code: baseline/code/                   # 基线代码快照（参考样本）
+  wiki: baseline/wiki/                   # 基线工程 wiki
 
 # Agent 运行时环境（规则、技能、工具、记忆）。
+# incoming_* 仅构建期：`svharness build --extra-skills` 将资源暂存于此并生成 manifest，S65 确认后分流写入 rules/skills。
 agent_env:
   rules: agent-env/rules/
   skills: agent-env/skills/
+  incoming_root: agent-env/_incoming/
+  incoming_skills_dir: agent-env/_incoming/skills/
+  incoming_manifest: agent-env/_incoming/manifest.yaml
   tools: agent-env/tools/
   memory:
     categories_dir: agent-env/memory/categories/

package/templates/_shared/skeleton/baseline/code/.gitkeep

@@ -0,0 +1 @@
+  

package/templates/_shared/skeleton/baseline/wiki/.gitkeep

@@ -0,0 +1 @@
+ 

package/templates/_shared/skeleton/references/apply-skills-registry.example.yaml

@@ -0,0 +1,11 @@
+# 示例：S60 为「内容引用」追加登记到此文件（勿在 agent-env/skills 下建 harness-apply-skills-*）。
+# svharness apply 将 enabled 项写入 harness-apply-skills-main 的 apply_skill_registry。
+schema_version: 1
+generated_at: "2026-05-17T00:00:00.000Z"
+skills:
+  - skill_dir: harness-apply-skills-example-topic
+    skill_name: harness-apply-skills-example-topic
+    source_id: REF-EXAMPLE-001
+    reference_md: references/md/example.md
+    description: 示例：按 references/md 中的流程执行某类任务
+    enabled: true

package/templates/_shared/skeleton/references/md/.gitkeep

@@ -0,0 +1 @@
+  

package/templates/_shared/skeleton/references/raw/.gitkeep

@@ -0,0 +1 @@
+  

package/templates/_shared/skeleton/references/yaml/.gitkeep

@@ -0,0 +1 @@
+  

package/templates/_shared/skeleton/requirements/md/.gitkeep

@@ -0,0 +1 @@
+  

package/templates/_shared/skeleton/requirements/raw/.gitkeep

@@ -0,0 +1 @@
+  

package/templates/_shared/skeleton/requirements/yaml/.gitkeep

@@ -0,0 +1 @@
+  

package/templates/android-xml/skeleton/agent-env/skills/harness-android-cli/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: harness-android-cli
+description: 使用 `android` 命令行工具编排 Android 开发任务，包括项目创建、部署、ADB 调试和 SDK 管理。
+---
+
+# Android CLI 工具
+
+## 项目创建
+
+```bash
+# 创建新项目
+android create project \
+    --name MyApp \
+    --package com.example.myapp \
+    --activity MainActivity \
+    --target android-34 \
+    --path ./MyApp
+
+# 创建模块
+android create lib-project \
+    --name my-library \
+    --package com.example.library \
+    --target android-34 \
+    --path ./my-library
+```
+
+## ADB 调试
+
+```bash
+# 安装与卸载
+adb install -r app-debug.apk
+adb uninstall com.example.myapp
+
+# 日志
+adb logcat -v threadtime
+adb logcat -s MainActivity:V *:S
+
+# Intent 启动
+adb shell am start -n com.example.myapp/.MainActivity
+adb shell am broadcast -a com.example.MY_ACTION
+
+# 查看 Activity 栈
+adb shell dumpsys activity activities
+```
+
+## SDK 管理
+
+```bash
+# 列出已安装和可用包
+android sdk list --all
+
+# 安装 SDK 版本
+android sdk install "platforms;android-34"
+android sdk install "build-tools;34.0.0"
+```
+
+## ProGuard / R8
+
+```bash
+# 生成混淆映射文件（release 构建后位于 build/outputs/mapping/）
+# 查看混淆堆栈
+retrace.sh -verbose mapping.txt stacktrace.txt
+```
+
+## 签名与对齐
+
+```bash
+# 对齐
+zipalign -v -p 4 app-release-unsigned.apk app-release-aligned.apk
+
+# 签名
+apksigner sign --ks my-release-key.jks \
+    --ks-key-alias my-alias \
+    --out app-release.apk app-release-aligned.apk
+
+# 验证签名
+apksigner verify --verbose app-release.apk
+```
+
+## 资源与 AAPT
+
+```bash
+# 查看 APK 包名和版本
+aapt dump badging app-release.apk
+
+# 列出 APK 权限
+aapt dump permissions app-release.apk
+```