preset-creator

Preset Creator 用于创建、审查或更新 Harness Anything 的 preset-manifest/v3 预设包。

用途

预设包是声明优先的包。预设特有的行为应放在包资产或脚本中，不得在 CLI 核心中按预设 id、标题或动作名添加分支。

包结构

一个自包含包包含：

<preset-id>/ preset.json PRESET.md policy.json # 仅当 policyPath 声明时 scripts/ # 仅当某个入口点声明脚本时

PRESET.md 使用如下 frontmatter：

---

schema: preset-document/v1 description: One sentence describing the supplied workflow or shape. whenToUse: One sentence naming the triggering situation.

清单 v3

使用 schema: "preset-manifest/v3"。必需的顶层键恰好为：schema、id、title、vertical、version、kind、outputShape、kernelVersionRange、capabilityImports、profiles、defaultProfile。可选顶层键为 extends、policyPath、entrypoints。不接受其他顶层键。kind 为 template-content 或 process-action。outputShape 是必需的非空字符串。

每个 profile 需要 id、title、completionGates、templateSelections；可添加 checkerProfile 和 capabilityImports。completionGates 是 gate-id 字符串数组，没有门时也要显式写空数组。defaultProfile 必须指向一个已声明的 profile。

每个模板选择恰好为：

{ "slot": "task.plan", "templateRef": "template://planning/task-plan@1", "materializeAs": "task_plan.md", "localePolicy": { "prefer": "project", "fallback": "en-US" } }

localePolicy.prefer 为 project、preset 或 explicit；fallback 为 zh-CN 或 en-US。

顶层 capabilityImports 项需要 id、kind、version 和布尔值 required。profile 与入口点的 capability 项使用 id、kind、version，以及可选的布尔值 required。有效的 kind 为 checker、scaffold、projection、command、template、raw-fs。

最小有效包

使用如下清单形态：

{ "schema": "preset-manifest/v3", "id": "example-note", "title": "Example Note", "vertical": "software/coding", "version": "1.0.0", "kind": "template-content", "outputShape": "repository-diff", "kernelVersionRange": { "min": "1.0.0", "maxExclusive": "2.0.0" }, "capabilityImports": [], "profiles": [ { "id": "baseline", "title": "Baseline", "checkerProfile": "standard", "completionGates": ["ci", "code-doc-reconciliation"], "templateSelections": [] } ], "defaultProfile": "baseline" }

校验包目录，而非单个清单文件：

ha preset validate --source /path/to/example-note --json

仅当报告为 "valid": true 且 issues 数组为空时继续。

脚本入口点

v3 入口点是具名对象，字段恰好为：

{ "type": "script", "intent": "Produce a bounded preset result.", "inputs": [ { "name": "title", "type": "string", "required": true } ], "requires": [ { "id": "capability:input/v1", "kind": "command", "version": "1" } ], "produces": [ { "id": "capability:result/v1", "kind": "projection", "version": "1" } ], "sideEffects": [], "command": "scripts/run.mjs" }

输入类型为 string、number、boolean 或 json。intent 是普通字符串。requires、produces、sideEffects 是扁平 capability-ref 数组。command 路径必须指向包内常规文件。脚本从 HARNESS_PRESET_CONTEXT 读取上下文；不要臆造未声明的文件系统权限。

从 v2 迁移

不要只给 v2 对象换标签而保留其字段。应用以下映射：

• 缺失时添加必需的顶层 outputShape。
• 保留 profile id、title、可选 checker profile、字符串 completion-gate id，以及有效的当前模板选择。
• 仅当类型和必需性明确时，将脚本输入从对象/映射转换为 v3 的 {name,type,required} 数组。
• 仅当结构化/对象 intent 的确切用户可见含义存在时，将其转换为单个普通字符串。
• 仅当当前 provider 明确已知时，将嵌套 capability 选择器替换为扁平的 requires、produces、sideEffects 引用。
• 丢弃 v2 的原始文件系统读写 path-glob 字段。它们在 v3 清单中没有对应项。raw-fs capability 引用命名的是 provider，并不恢复那些旧路径范围。
• 移除任何无法在不猜测的情况下表达其权限或输入含义的入口点。将其用户可见流程保留在 PRESET.md 中，并向所有者报告被移除的行为。
• 删除所有未知 v2 键。校验是精确字段的，且失败即关闭。

模板资产

预设清单选择模板；vertical 模板目录拥有模板元数据，Markdown 资产拥有正文。使用 template://<id>@<version> 引用。不要在清单中内联模板正文。运行 ha template list 以发现当前内置声明，并校验每个选定的 slot、路径、locale policy 和必需锚点都能解析。

工作流

1. 用一句话说明预设任务，并选择 template-content 或 process-action。
2. 阅读 v3 契约和附近的内置清单；不要复制 v2 schema。
3. 创建 preset.json 和 PRESET.md，然后仅添加已声明的 policy、template 或 script 文件。
4. 运行 ha preset validate --source <package-directory> --json。
5. 安装前运行 ha preset install --source <package-directory> --dry-run --json 并检查其 issues。
6. 在与行为匹配的层级添加 resolver、materialization、permission 或 execution 测试。在每个新 Node 测试文件的第一行恰好放置一个 // harness-test-tier: 声明。

审查清单

• schema 为 preset-manifest/v3；outputShape 存在。
• 顶层、profile、selection、capability、input 和 entrypoint 字段都是当前契约的精确字段。
• profiles 非空且 defaultProfile 可解析。
• completion gates 是字符串 id；template selections 使用当前嵌套 locale policy。
• 没有 v2 的 reads、writes、对象 input/intent 或嵌套 capability 选择器残留。
• PRESET.md 具有有效的 preset-document/v1 frontmatter。
• 包校验报告 valid 且无 issues。
• 未向通用 CLI 分发添加预设特有行为。