svharness 0.8.0

package/templates/_shared/build-skills/harness-build-skill-spec-builder.md

@@ -0,0 +1,85 @@
+---
+name: harness-build-skill-spec-builder
+description: >
+  将需求文档转化为结构化 specs。驱动 raw → requirements → specs 两阶段管线，
+  并对产物做 specs/*/schema.json 校验。当用户说"条目化需求"、"生成 specs"、"构建 signals/ui/behavior/interfaces specs"、
+  "structure requirements"、或由 harness-build-skill-orchestrator 委派给本 skill 时触发。
+---
+
+# harness-build-skill-spec-builder（规格构建器）
+
+你每次只处理一个模块，把原始需求转化为**可被 schema 校验通过**的 specs。
+
+## 输入
+
+- `__HARNESS_ROOT__assets/raw/*.{md,xlsx,pdf,txt}` —— 原始需求文档
+- `__HARNESS_ROOT__assets/requirements/*.requirements.yaml` —— 已条目化的结构化需求项（如已存在）
+- `__HARNESS_ROOT__specs/<layer>/schema.json` —— 每一层的校验目标
+- `__HARNESS_ROOT__harness.yaml` —— 确认哪些层当前激活
+
+## 两阶段管线
+
+### 阶段 A：raw → requirements（条目化）
+
+对 `__HARNESS_ROOT__assets/raw/` 下每个文件，产出一个 `__HARNESS_ROOT__assets/requirements/<module>.requirements.yaml`，结构如下：
+
+```yaml
+module: <module>
+source_doc: "assets/raw/<file>"
+extracted_at: <ISO8601 日期>
+items:
+  - id: REQ-<MODULE>-001
+    category: functional | non-functional | constraint
+    priority: must | should | may
+    description: "一句话陈述需求"
+    acceptance: "如何验证该需求满足"
+    traces_to:
+      - specs/<layer>/<module>.<layer>.yaml#<anchor>
+```
+
+规则：
+- 条目 id **稳定**：一旦产出不得改写，新条目追加。
+- 每条 `description` 必须是**一句清晰的陈述**。
+- `traces_to` 初始可为空，阶段 B 生成 specs 后回填。
+
+### 阶段 B：requirements → specs（规格生成）
+
+对每个模块、每个激活层（signals / ui / behavior / interfaces）：
+
+1. 读取 `__HARNESS_ROOT__assets/requirements/<module>.requirements.yaml`。
+2. 读取 `__HARNESS_ROOT__specs/<layer>/schema.json`。
+3. 生成 `__HARNESS_ROOT__specs/<layer>/<module>.<layer>.yaml`，要求：
+   - 满足 schema（所有 `required` 字段完备、`enum` 取值合法）
+   - 在本层的语义内回答相关需求条目
+4. 回填 `traces_to`：在 `requirements` 中把 spec 的路径/锚点记回对应条目。
+5. 校验 YAML 是否通过 schema（优先使用本地校验器；若无，对照 schema 的 `required` 与 `enum` 手动核对）。
+
+## 状态更新
+
+每完成一个模块后：
+- 更新 `__HARNESS_ROOT__.harness-build-state.yaml`（阶段 P3 或 P4，带每层子状态）。
+- 刷新状态文件与 spec 文件的 `updated_at`。
+
+## 守则（不得违反）
+
+- **不得无中生有**：所有需求必须来自 `__HARNESS_ROOT__assets/raw/`。`assets/raw/` 为空或仅含 `.gitkeep` 时，**必须以表单方式提示用户放入需求文档**，禁止自行生成占位内容。
+- **不得修改 `schema.json`**：schema 若有问题，停下来告诉用户，不要自行改写。
+- 单个 spec YAML 文件应保持 **< 300 行**；超过时按子模块拆分。
+- 一个 YAML 文件只承载一个层，**不要混层**。
+- 所有向用户的反馈使用中文；字段名、枚举值、CMD ID 等保留英文。
+- **必须以表单方式**与用户交互确认，禁止仅以纯文本输出后自行继续（见 `harness-build-rule-user-interaction`）。
+- **所有描述性字段必须使用中文**（见 `harness-build-rule-chinese-only`）。
+
+## 必须遵守的构建规则（位于 Agent rules 目录）
+
+本 skill 执行前必须加载并严格遵循（文件位于当前 agent 的 rules 目录，具体路径/扩展名
+随 agent 可能为 `.md` 或 `.mdc`）：
+
+- `harness-build-rule-specs-schema` — specs 四域固定、schema.json 必过、字段增减需同步。
+- `harness-build-rule-orchestrator-flow` — 本 skill 仅服务 P3/P4，禁止跨阶段跳步。
+- `harness-build-rule-agent-agnostic` — 生成的 requirements/specs YAML 严禁出现具体 agent 名或私有语法。
+- `harness-build-rule-memory-write` — 条目化/规格化过程中产生的可复用经验按规范写入 memory。
+- `harness-build-rule-chinese-only` — 所有产出内容必须使用中文（字段名、枚举值等保留英文）。
+- `harness-build-rule-user-interaction` — 用户交互铁律：等待 raw 文档、表单确认、禁止擅自修改。
+
+若规则文件缺失，停止工作并提示用户重新运行 `svharnessbuild init`。

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

@@ -0,0 +1,77 @@
+---
+name: harness-build-skill-wiki-writer
+description: >
+  逐页撰写 baseline wiki 正文。读取 state 中 `tasks_file` 指向的任务清单与 structure.xml，
+  基于 assets/baseline/code/ 下的源码快照产出每一页 Markdown。当用户说"生成 baseline wiki 正文"、
+  "按 TASKS.md 逐页生成 baseline wiki"、"继续写 wiki 下一页"，或由 harness-build-skill-orchestrator
+  在阶段 P1_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` → `P1_wiki.tasks_file` —— 任务清单路径（通常 `__HARNESS_ROOT__assets/baseline/wiki/TASKS.md`）；
+  复选框形态，`[ ]` 待办、`[x]` 已完成
+- `__HARNESS_ROOT__assets/baseline/wiki/structure.xml` —— outline 权威来源；title / sectionFolder / parentSection 以此为准
+- `__HARNESS_ROOT__assets/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`、
+   `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>`。
+5. 写完后最小补丁式修改 `TASKS.md`，把该任务的 `[ ]` 改为 `[x]`（不得重排任务顺序、不得删除其他行）。
+6. 默认单步询问是否继续下一页。如果用户说"批量"、"全部继续"、"run through"，则连续处理至清单尾。
+
+## 撰写规则（强制，与 --generate-wiki 的产出口径必须一致）
+
+- **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)`
+  - Sources 行：`Sources: <repo-relative>/Foo.java:10-30, <repo-relative>/Bar.kt:5-8`
+  `<repo-relative>` 是**相对 `__HARNESS_ROOT__assets/baseline/code/` 的路径**，既不是仓库原始绝对路径，
+  也不是 wiki md 文件的相对路径。行号采用 `start-end`（闭区间）。
+- 禁止粘贴大段代码：单个 code block ≤ 40 行；必要时用省略号 `// ...` 裁剪。
+- 所有中文段落使用中文标点；字段名、类名、路径保留英文不译。
+
+## 产出
+
+- `__HARNESS_ROOT__assets/baseline/wiki/<lang>/<section>/<stem>.md` —— 每个 task 一份
+- 更新后的 `TASKS.md` —— 状态位从 `[ ]` 推进为 `[x]`，其他内容不动
+
+## 守则（不得违反）
+
+- **不得凭空编造代码或结论**：任何结论都必须可追溯到 `__HARNESS_ROOT__assets/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。
+- 所有面向用户的说明使用中文；字段名、路径、类名保留英文。
+- **必须以表单方式**与用户交互确认，禁止仅以纯文本输出后自行继续。
+- **所有 wiki 正文段落必须使用中文**（代码、类名、路径等保留英文）。
+
+## 必须遵守的构建规则（位于 Agent rules 目录）
+
+本 skill 执行前必须加载并严格遵循（文件位于当前 agent 的 rules 目录，具体路径/扩展名
+随 agent 可能为 `.md` 或 `.mdc`）：
+
+- `harness-build-rule-orchestrator-flow` — 本 skill 仅服务 P1_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`。

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

@@ -0,0 +1,53 @@
+# AGENTS.md
+
+> 本文件是任何 AI 编码 Agent 接入 **<%= name %>** 项目的入口。
+> 请**按顺序**完成以下步骤，不要跳步。
+
+## 1. 加载上下文（只读）
+
+在做出任何编辑之前，请先阅读：
+
+1. `harness.yaml` —— 清单：各层路径、版本、当前 agent
+2. `.harness-build-state.yaml` —— 当前构建阶段与待办动作
+3. `specs/**/*.yaml` —— 权威的「做什么」（功能契约，唯一事实来源）
+4. `agent-env/rules/*.mdc` —— 架构层面的「怎么做」（不得违反的约束）
+5. `assets/baseline/wiki/**/*.md` —— 基线源码知识快照（指引，不是契约）
+
+## 2. 查看状态，选择下一步
+
+- 打开 `.harness-build-state.yaml`
+- 识别 `current_phase`
+- 优先调用 `next_action` 中建议的 skill
+- `P1_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-wiki-writer** —— 按 TASKS.md 逐页撰写 baseline wiki 正文
+
+## 3. 产出
+
+- 所有代码必须同时满足 `specs/`（做什么）与 `agent-env/rules/`（怎么做）。
+- 任何与 specs 的偏离都视为 bug —— 先提 spec 变更，再写代码。
+- 新沉淀的经验知识放入 `agent-env/memory/inbox/`，待人工审核后转入 `agent-env/memory/categories/`。
+
+## 4. 更新状态
+
+每完成一个有意义的步骤后：
+
+- 更新 `.harness-build-state.yaml`（阶段状态与 `updated_at`）
+- 对被修改的 spec 提升模块级 `version`
+- 在 `CHANGELOG.md` 追加记录
+
+## 5. 交付前的校验
+
+- 任何涉及 specs 的任务，产物必须通过 `specs/*/schema.json` 的校验
+- 代码改动不得违反 `agent-env/rules/` 中的规则
+- 在 PR 描述中记录每一条外部假设
+
+---
+
+架构: **<%= arch %>**　　Agent: **<%= agent %>**　　脚手架生成时间: <%= createdAt %>

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

@@ -0,0 +1,15 @@
+# Changelog
+
+本 harness 的所有重要变更记录在此，遵循语义化版本（SemVer）。
+
+## [0.1.0] - <%= createdAt.substring(0, 10) %>
+
+### Added
+- 由 svharnessbuild v<%= version %> 初次生成骨架（架构：<%= arch %>，Agent：<%= agent %>）。
+- 建立分层目录结构：`specs/` / `assets/` / `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。
+<% if (sourcePath) { -%>
+- 已登记基线源码路径：`<%= sourcePath %>`。
+<% } -%>

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

@@ -0,0 +1,51 @@
+# <%= name %> harness
+
+面向 **<%= name %>** 项目的 SDD-Driven Agent-Agnostic Coding Framework（架构：`<%= arch %>`）。
+
+由 **svharnessbuild v<%= version %>** 于 <%= createdAt %> 生成。
+
+## 这是什么？
+
+一个**分层 harness**，为本项目提供可靠的 AI Agent 协作底座：
+
+| 层 | 职责 |
+|----|------|
+| `specs/` | 权威的「做什么」 —— signals / UI / behavior / interfaces（通过 schema 校验的 YAML） |
+| `assets/` | 输入与基线 —— `raw/`、`requirements/`、`baseline/{code,wiki}/` |
+| `agent-env/` | Agent 运行时环境 —— `rules/`、`skills/`、`tools/`、`memory/{categories,inbox}/` |
+| `tasks/` | 声明式 task 模板（`templates/`），通过路径引用 specs / rules / skills |
+| `commands/` | 命令式工作流 —— `install/`（一次性初始化）、`update/`（日常治理） |
+
+## 如何构建
+
+除骨架外的一切，均由 **Agent 驱动** 生成。在你的 AI 会话中说：
+
+> **开始构建 harness**（或 `begin harness build`）
+
+注入的 **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
+
+## 常用命令
+
+```bash
+cat .harness-build-state.yaml           # 查看当前进度
+ls specs/*/                             # 按层查看 specs
+ls .<agent>/skills/                     # 查看构建辅助 skill
+```
+
+<% if (sourcePath) { -%>
+## Baseline 模式（反向提取）
+
+基线源码：`<%= sourcePath %>`
+
+本次使用既有代码反向提取 specs：orchestrator 会先从源码抽取规格草稿，
+待你人工审核完成后再将 `bootstrap_mode` 翻转为 false。
+<% } -%>

package/templates/_shared/meta/VERSION.ejs

@@ -0,0 +1 @@
+0.1.0

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

@@ -0,0 +1,52 @@
+# Harness 清单文件 —— 由 svharnessbuild 初次生成，后续由 Agent 按需增量更新。
+schema_version: "1.0"
+name: "<%= name %>"
+arch: "<%= arch %>"
+agent: "<%= agent %>"
+version: "0.1.0"
+created_at: "<%= createdAt %>"
+scaffolder:
+  tool: svharnessbuild
+  version: "<%= version %>"
+
+# SDD 规格层（均带 schema 校验）。
+specs:
+  bootstrap_mode: true   # 所有 specs 通过人工审核后置为 false
+  layers:
+    - { name: signals,    schema: specs/signals/schema.json }
+    - { name: ui,         schema: specs/ui/schema.json }
+    - { 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
+
+# Agent 运行时环境（规则、技能、工具、记忆）。
+agent_env:
+  rules: agent-env/rules/
+  skills: agent-env/skills/
+  tools: agent-env/tools/
+  memory:
+    categories_dir: agent-env/memory/categories/
+    inbox_dir: agent-env/memory/inbox/    # 待审核的新沉淀记忆
+
+# Task 模板（通过路径引用 specs / rules / skills）。
+tasks:
+  templates_dir: tasks/templates/
+
+# 命令式工作流（Agent 按需触发）。
+commands:
+  install_dir: commands/install/          # 一次性初始化/安装类命令
+  update_dir: commands/update/            # 日常治理/更新类命令
+
+# baseline 源码路径（可选）：存在时启用反向提取模式。
+<% if (sourcePath) { -%>
+source: "<%= sourcePath %>"
+<% } else { -%>
+source: null
+<% } -%>

package/templates/_shared/skeleton/agent-env/memory/categories/.gitkeep

@@ -0,0 +1 @@
+# placeholder — memory categories (long-lived knowledge)

package/templates/_shared/skeleton/agent-env/memory/inbox/.gitkeep

@@ -0,0 +1 @@
+# placeholder — pending memory candidates awaiting review

package/templates/_shared/skeleton/agent-env/skills/.gitkeep

@@ -0,0 +1 @@
+# placeholder — project-specific skills injected here

package/templates/_shared/skeleton/agent-env/tools/.gitkeep

@@ -0,0 +1 @@
+# placeholder — harness build/parse tools (python/ps1)

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

@@ -0,0 +1 @@
+# placeholder — reference code snapshots (~20 key files), NOT full src copy

package/templates/_shared/skeleton/assets/baseline/repomix/.gitkeep

@@ -0,0 +1 @@
+

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

@@ -0,0 +1 @@
+# placeholder — repowiki pages rendered by harness-knowledge-builder skill

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

@@ -0,0 +1 @@
+# placeholder — populated during harness build (manual requirement docs)

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

@@ -0,0 +1 @@
+# placeholder — populated during harness build (parsed/structured requirements)

package/templates/_shared/skeleton/commands/install/.gitkeep

@@ -0,0 +1 @@
+# placeholder — agent bootstrap adapters (PS1 / shell)

package/templates/_shared/skeleton/commands/update/.gitkeep

@@ -0,0 +1 @@
+# placeholder — maintainer scripts (drift check, memory audit, asset sync)

package/templates/_shared/skeleton/specs/behavior/schema.json

@@ -0,0 +1,39 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "harness://specs/behavior/schema.json",
+  "title": "行为规格 Schema",
+  "description": "描述模块的状态、守卫条件与转移。",
+  "type": "object",
+  "required": ["module", "version", "states", "transitions"],
+  "properties": {
+    "module": { "type": "string" },
+    "version": { "type": "string", "pattern": "^\\d+\\.\\d+\\.\\d+$" },
+    "initial_state": { "type": "string" },
+    "states": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["name"],
+        "properties": {
+          "name": { "type": "string" },
+          "description": { "type": "string" }
+        }
+      }
+    },
+    "transitions": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["from", "to", "trigger"],
+        "properties": {
+          "from": { "type": "string" },
+          "to": { "type": "string" },
+          "trigger": { "type": "string" },
+          "guard": { "type": "string" },
+          "action": { "type": "string" }
+        }
+      }
+    }
+  },
+  "additionalProperties": true
+}

package/templates/_shared/skeleton/specs/interfaces/schema.json

@@ -0,0 +1,38 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "harness://specs/interfaces/schema.json",
+  "title": "接口规格 Schema",
+  "description": "描述模块对外暴露或对外依赖的 AIDL / HTTP / IPC 契约。",
+  "type": "object",
+  "required": ["module", "version", "interfaces"],
+  "properties": {
+    "module": { "type": "string" },
+    "version": { "type": "string", "pattern": "^\\d+\\.\\d+\\.\\d+$" },
+    "interfaces": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["name", "kind"],
+        "properties": {
+          "name": { "type": "string" },
+          "kind": { "type": "string", "enum": ["aidl", "http", "ipc", "binder", "custom"] },
+          "methods": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "required": ["name"],
+              "properties": {
+                "name": { "type": "string" },
+                "params": { "type": "array", "items": { "type": "object" } },
+                "returns": { "type": "string" },
+                "description": { "type": "string" }
+              }
+            }
+          }
+        },
+        "additionalProperties": true
+      }
+    }
+  },
+  "additionalProperties": true
+}

package/templates/_shared/skeleton/specs/signals/schema.json

@@ -0,0 +1,37 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "harness://specs/signals/schema.json",
+  "title": "信号规格 Schema",
+  "description": "描述一组在 ECU 与本应用之间流转的 MCU/HMI 信号。",
+  "type": "object",
+  "required": ["module", "version", "signals"],
+  "properties": {
+    "module": { "type": "string", "minLength": 1 },
+    "version": { "type": "string", "pattern": "^\\d+\\.\\d+\\.\\d+$" },
+    "signals": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["id", "name", "direction", "type"],
+        "properties": {
+          "id": { "type": "string", "pattern": "^CMDID_[A-Z0-9_]+$" },
+          "name": { "type": "string" },
+          "direction": { "type": "string", "enum": ["car2hmi", "hmi2car", "bidirectional"] },
+          "type": { "type": "string", "enum": ["int", "bool", "enum", "byte-array", "float"] },
+          "length_bytes": { "type": "integer", "minimum": 1 },
+          "default": {},
+          "enum_values": {
+            "type": "array",
+            "items": { "type": "object", "required": ["value", "meaning"] }
+          },
+          "traces_to": {
+            "type": "array",
+            "items": { "type": "string" }
+          }
+        },
+        "additionalProperties": true
+      }
+    }
+  },
+  "additionalProperties": true
+}

package/templates/_shared/skeleton/specs/ui/schema.json

@@ -0,0 +1,44 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "harness://specs/ui/schema.json",
+  "title": "UI 规格 Schema",
+  "description": "描述一个 Compose 界面或组件树及其交互契约。",
+  "type": "object",
+  "required": ["module", "version", "components"],
+  "properties": {
+    "module": { "type": "string" },
+    "version": { "type": "string", "pattern": "^\\d+\\.\\d+\\.\\d+$" },
+    "figma_source": { "type": "string", "format": "uri" },
+    "ue_spec_ref": { "type": "string" },
+    "components": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["id", "type"],
+        "properties": {
+          "id": { "type": "string" },
+          "type": {
+            "type": "string",
+            "enum": ["Switch", "Slider", "Button", "Tab", "Checkbox", "RadioButton", "Text", "Image", "Custom"]
+          },
+          "figma_node_id": { "type": "string" },
+          "bound_signal": { "type": "string" },
+          "states": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "required": ["name"],
+              "properties": {
+                "name": { "type": "string" },
+                "visual": { "type": "string" },
+                "condition": { "type": "string" }
+              }
+            }
+          }
+        },
+        "additionalProperties": true
+      }
+    }
+  },
+  "additionalProperties": true
+}

package/templates/android-compose/skeleton/agent-env/rules/harness-compose-mandatory.mdc

@@ -0,0 +1,49 @@
+---
+description: Jetpack Compose 编码铁律，所有 Compose 代码必须遵守
+alwaysApply: true
+---
+
+# Compose 编码铁律
+
+## 状态管理
+
+### Composable 必须无状态
+- 正例：`fun MyComponent(value: String, onValueChange: (String) -> Unit, modifier: Modifier = Modifier)`
+- 反例：`fun MyComponent()` 内部 `remember { mutableStateOf(...) }` 且不向上暴露
+- 检测：grep `@Composable` 函数内出现 `= mutableStateOf` 且非状态提升模式
+
+### Modifier 必须作为第一个可选参数
+- 正例：`fun Card(title: String, modifier: Modifier = Modifier)`
+- 反例：`fun Card(modifier: Modifier, title: String)` — modifier 不在第一个可选位置
+- 检测：grep `@Composable` 函数签名中 `modifier` 参数位置不在默认参数首位
+
+## 副作用
+
+### 禁止在组合体内直接执行副作用
+- 正例：`LaunchedEffect(userId) { viewModel.loadUser(userId) }`
+- 反例：`fun MyScreen() { viewModel.loadData() }` — 每次重组都会调用
+- 检测：grep `@Composable` 函数体内直接调用 ViewModel 方法且未包裹在 LaunchedEffect/DisposableEffect 中
+
+## 性能
+
+### LazyColumn/LazyRow 的 items 必须提供 key
+- 正例：`items(users, key = { it.id }) { user -> UserItem(user) }`
+- 反例：`items(users) { user -> UserItem(user) }` — 无 key，列表更新效率低
+- 检测：grep `items(` 后无 `key =` → 违规
+
+### 昂贵计算必须用 remember + derivedStateOf 包裹
+- 正例：`val filtered by remember(items) { derivedStateOf { items.filter { ... } } }`
+- 反例：`val filtered = items.filter { ... }` — 每次重组都重新计算
+- 检测：grep `@Composable` 函数体内 `.filter` / `.sortedBy` / `.map` 且未包裹在 remember 中
+
+### 禁止使用不稳定类型作为 Composable 参数
+- 正例：`fun ItemList(items: List<Item>)` — `List` 是稳定接口
+- 反例：`fun ItemList(items: MutableList<Item>)` — `MutableList` 不稳定，阻止跳过
+- 检测：grep `@Composable` 函数参数中出现 `MutableList` / `MutableMap` / `SparseArray`
+
+## 主题
+
+### 使用 MaterialTheme 而非硬编码颜色/字体
+- 正例：`MaterialTheme.colorScheme.primary`、`MaterialTheme.typography.bodyLarge`
+- 反例：`Color(0xFF6200EE)`、`TextStyle(fontSize = 16.sp)` — 硬编码无法适配暗色模式
+- 检测：grep `@Composable` 函数内出现 `Color(0x` 或 `TextStyle(fontSize` 且未引用 `MaterialTheme`

package/templates/android-compose/skeleton/agent-env/rules/harness-coroutines-scope.mdc

@@ -0,0 +1,52 @@
+---
+description: Kotlin 协程作用域与生命周期约束，防止泄漏与错误并发
+alwaysApply: true
+---
+
+# 协程作用域约束
+
+## 作用域选择
+
+### 禁止使用 GlobalScope
+- 正例：`viewModelScope.launch { ... }`、`lifecycleScope.launch { ... }`
+- 反例：`GlobalScope.launch { ... }` — 永远不取消，内存泄漏
+- 检测：grep `GlobalScope` 出现于生产代码
+
+### ViewModel 中使用 viewModelScope
+- 正例：`viewModelScope.launch { repository.fetch() }` — ViewModel 清除时自动取消
+- 反例：`CoroutineScope(Dispatchers.IO).launch { ... }` — 手动创建作用域，不跟随生命周期
+- 检测：grep ViewModel 类内 `CoroutineScope(` 手动创建
+
+### 禁止在主线程使用 runBlocking
+- 正例：`viewModelScope.launch { withContext(Dispatchers.IO) { api.fetch() } }`
+- 反例：`fun loadData() { runBlocking { api.fetch() } }` — 阻塞主线程
+- 检测：grep `runBlocking` 出现于非测试代码
+
+## 调度器
+
+### IO 操作必须切换到 Dispatchers.IO
+- 正例：`withContext(Dispatchers.IO) { database.query() }`
+- 反例：在 `Dispatchers.Main` 上执行网络/数据库操作
+- 检测：grep Room `@Dao` 方法在 Main 调度器上调用
+
+### 注入调度器而非硬编码
+- 正例：`@Inject constructor(@DispatcherIO private val ioDispatcher: CoroutineDispatcher)`
+- 反例：硬编码 `Dispatchers.IO` 散落在业务代码各处
+- 检测：grep UseCase/Repository 中硬编码 `Dispatchers.IO` 且未通过构造函数注入
+
+## Flow 收集
+
+### Compose 中必须使用 collectAsStateWithLifecycle
+- 正例：`val state by viewModel.uiState.collectAsStateWithLifecycle()`
+- 反例：`val state by viewModel.uiState.collectAsState()` — 不感知生命周期，后台仍在收集
+- 检测：grep `collectAsState()` 且无 `WithLifecycle` 后缀
+
+### Fragment/Activity 中必须使用 repeatOnLifecycle
+- 正例：`viewLifecycleOwner.repeatOnLifecycle(Lifecycle.State.STARTED) { viewModel.uiState.collect { ... } }`
+- 反例：`lifecycleScope.launch { viewModel.uiState.collect { ... } }` — 不感知生命周期
+- 检测：grep `lifecycleScope.launch` 后直接 `.collect` 且无 `repeatOnLifecycle`
+
+### SharedFlow 必须使用 replay=0
+- 正例：`MutableSharedFlow<Effect>(replay = 0)` — 一次性消费
+- 反例：`MutableSharedFlow<Effect>(replay = 1)` — 新订阅者收到旧事件
+- 检测：grep `MutableSharedFlow` 构造参数 `replay` 值大于 0