Henji Application Capability

痕迹AI 应用能力适配

当前适用范围

UI、内置 Pi 与现代 MCP 共用正式领域服务和应用运行实例。公共契约位于 src/core/application-control/，渲染层在 src/features/application-control/ 装配各领域，Electron 的 services/application-runtime/ 协调授权、执行、账本、费用与恢复，先于 Pi 和 MCP 初始化。

Pi 与 MCP 只负责工具和结果投影，不拥有业务状态。MCP 固定使用正式协议 2026-07-28 与拆分 SDK 2.0.0，拒绝旧协议；授权逐请求核验，持久操作不随网络连接结束。旧自研助手、Henji Script、发现租约和旧前端工具桥已移除，不保留兼容执行链或旧数据迁移要求。

将领域能力接入公共注册和执行入口。先找正式业务服务，再声明或扩展实体；不要为 Pi 或 MCP 复制业务实现。

执行流程

路由分级（先于第 0 步）：命中 skill 不等于新增 MCP 工具

先回答下面七个问题，再决定工作深度：

1. 是否新增用户可读的数据、状态或设置？
2. 是否新增属性修改、集合增删或业务动作？
3. 是否新增长任务、付费、取消、恢复或迟到结果语义？
4. 是否新增跨工程／跨领域稳定引用？
5. 是否新增文件、网络、持久化、权限或其他副作用？
6. 是否新增页面、浮层、工具入口或可导航 Surface？
7. 是否只是把现有能力换一种布局、文案、样式或展示方式？

按答案分三级执行：

多个 skill 可以同时命中，但职责不能重复：henji-ui-surface 管界面层级与呈现，canvas-node-builder 管画布节点结构，henji-model-adaptation 管供应商与模型契约，本 skill 只管应用能力增量和覆盖证明。不要为满足 skill 数量制造额外适配层。

0. 先判断该不该写专用能力

默认不写。 反射层已经提供三个通用动词，领域只要注册实体和属性，助手就能用：

静态属性与 collectionWrite 只表示“结构上支持”。每个 provider 还必须通过 getPropertyAvailability / getCollectionAvailability 返回当前引用、模式和状态下的真实可用性；没有额外集合限制时复用 unrestrictedCollectionAvailability。计划、提交预检和每步执行前由统一事务引擎复核，领域服务里不再复制模式守卫。

describe_application_entities 可带 refs 查询实例级动态状态。recovery 只放结构化能力/实体/属性标识；任何操作步骤必须先通过正式 describe → change → read/真相源 结果测试，禁止凭读代码猜一条路线写进提示或错误。

只有当动作无法用属性写入表达时才写专用能力——例如"环绕运镜"要按角度采样算轨迹，"复用或布置对象"要做碰撞检测和复用判定。凡是"设置某某值""加一条记录"这类，一律走通用动词。

Camera Stage 只公开 camera_stage.state_keyframe。动画操作必须走已经过结果测试的路径：在同一次 change_application_entities 的 changes 中按顺序交替写 camera_stage.playback.current_time 与对象、角色或摄像机的 animatable.* / pose_preset，最后可在同一事务写 loop/playing；应用会自动创建或更新完整场景状态，任一步失败则整体回滚。除非后一步需要前一步新创建且尚未返回的引用，否则禁止按时间点拆成多轮调用。派生属性轨道只供播放与导出，不能注册为公开实体或持久化真相源。

多项实体写入使用同一通用事务，算法操作经正式领域能力执行。输入约束由反射和能力 schema 投影；跨领域使用完整稳定引用，不创建额外脚本编排入口。

声明了可写属性就必须注册 ApplicationMutationExecutor，声明了 collectionWrite 就必须注册 ApplicationCollectionExecutor。每个实体必须至少拥有一种写入执行器，或填写 writeExclusion.reason，明确说明为何只读以及状态由哪个正式模块或操作维护；不得用“暂时不支持”代替判断。三者由覆盖测试强制一致。

新增可写属性只在一处声明。 一个属性此前要碰 4 个位置（属性描述符、读取映射、写入表项、界面动作账本），缺任何一处都是静默失效——不报错，助手安静地少一块能力，只有用户实机撞上才发现（三维场景外观 24 项当初就是这样漏掉描述符和读取两处）。现在统一走 src/core/application-control/fieldDefinition.ts 的 ApplicationFieldDefinition：

sceneField('sky_color', '天空颜色', COLOR, {
  read: (settings) => settings.sky.color,
  write: (store, value) => store.setSceneSkyColor(value),
  storeAction: 'setSceneSkyColor',
})

一条声明用 fieldDescriptors() / fieldReadValues() / fieldWriterTable() / fieldLedgerEntries() 派生出描述符、读取映射、写入表项、账本条目四样东西，四个消费方各取所需。字段定义按领域收在 <领域>Fields.ts（如 cameraStageSceneFields.ts、canvasFields.ts、assetFields.ts），领域内部再包一层 <领域>Field() 薄封装填好该领域固定的 entityType、权限、revision scope。同一个 store 动作被多个字段共用时（如 updateObject 一次改 name/visible/color/character_variant 四个属性），fieldLedgerEntries() 按声明顺序把它们累进同一条账本绑定。禁止再分别手写这四处——统一定义之后漏一条是整条从四处一起消失，会被 storeActionCoverage 门禁当场抓到，而不是像以前那样只漏两处却全绿。

0.5 一次声明、多入口投影

同一份领域声明现在同时服务三个入口：应用界面、内置 Pi、外部智能体（MCP）。新增能力时只写一次声明，三个入口各自投影；任何一处出现第二份业务字段表都算缺陷。

由此得到几条硬要求：

• 不要在 electron/main/services/mcp/** 写任何业务字段、实体类型或属性清单。 那里只允许协议层自身的参数（操作标识、分块偏移、契约发现），业务参数一律从能力定义投影。前缀白名单尤其禁止——它和领域声明是两份真相，新增写域时必然漂移。
• 新增前端业务能力：在正式能力声明中登记参数、权限和控制影响，并接入正式执行器；MCP 工具集合、权限及参数自动投影，禁止再手写 MCP ID 白名单。语义写入必须声明 resolveOperationTargets，创建操作还要用 resolveOperationWriteTargets 绑定操作身份；纯导航由注册表统一绑定视图身份。
• 复用与排除在原声明中登记：普通读改增删使用通用实体入口；已有专用别名可声明 external.kind: delegate 和实际实体、操作及属性，覆盖检查必须证明它们确实开放且可写。内部协议写明 internal 原因，保存恢复写明 recovery 并仅走原操作账本。不得用排除掩盖缺失的业务执行器。
• 防遗漏从软件全集检查：applicationControlCoverage.test.ts 核对全部前端能力的 MCP 路由、执行器、目标绑定和委托字段，配合属性、集合、Surface 与 store 动作门禁。新增功能只留在组件里而不登记不算完成；必须加入现有正式注册入口。内置 Pi 默认延迟加载新领域工具，不需要跟着新增一份启用名单。
• 新增一个已登记的业务实体或属性，外部立刻可读可写，不需要回到 MCP 侧登记任何东西。做不到就说明有人加了第二份表。
• 有意只读必须写 writeExclusion.reason。它是"未完成"和"有意排除"在机器上唯一的区分方式，并且会原样出现在外部契约里，成为调用方改道的依据。不接受"暂时不需要"这类无法验证的表述。
• 契约变化同步正式消费者与测试：新格式由统一 schema 校验；不为本轮删除的旧执行链、旧协议或旧数据增加兼容分支。
• 参数错误必须点名字段。基础工具要能被直接调用并拿到具体错误；把校验失败和业务失败收敛成同一句兜底文案，等于逼调用方猜。
• 不能假设客户端支持高级扩展。发现、读取、修改、查任务、取结果五步必须都走普通 tools 调用：通知改成轮询查询工具，资源读取保留工具入口，审批留在痕迹 AI 内完成。降级不得放宽授权边界。

守这几条的门禁：electron/main/services/application-runtime/toolCatalog.test.ts（schema 同源与授权过滤）、src/features/application-control/externalCapabilityInventory.test.ts（八个业务写域与只读原因）、collectionCoverage.test.ts（每个实体要么能写要么写明原因）。

1. 判断能力边界

• 先定位正式业务服务，禁止让能力处理器复制业务逻辑。
• 专用能力与通用动词同时触达同一状态时，两条路径必须委托同一个正式业务服务。
• 判断执行位置：依赖 DOM、当前页面轻状态或即时视觉反馈时放渲染层；文件、数据库和系统权限由主进程协调；CPU 重计算放 Worker，像素处理复用正式 GPU／Worker 管线，领域状态留在所属服务。
• 将一个算法能力限定为一个可验证动作。确有预览/审批语义的查询、计划、提交可注册成独立原子 action，并共用领域状态和执行协调。禁止用一个开放参数工具承载任意操作。
• 后台能够完成的操作不要切换页面；只有用户明确要求查看、定位或进入编辑器时才使用 Surface 能力。
• “不要切换/不要删除”等负向约束由 Gateway 与审批边界承担；最终说明须用 Effect Receipt 反查这类事实，禁止否认已经发生的副作用。

2. 定义原生能力

• 实体、属性和集合 CRUD 在 Application Control 反射注册表中声明，由通用实体工具投影；不得为它们再写同义的专用能力。
• 只有无法用 CRUD 表达的算法操作，才在 src/core/application-control/domains/ 的领域能力模块中声明 ApplicationCapabilityDefinition 并注册到统一目录，由公共应用入口调用。
• 使用稳定、小写的能力 ID；版本从 1 开始，破坏性契约变化才升级版本。
• 完整声明输入/输出 schema、AI 输入 schema、领域、别名、读写属性、风险、数据等级、权限、超时、幂等、撤销、预览、作用域、可用条件、前置能力、并发键、引用类型、成功证据和失败恢复。
• AI 输入 schema 顶层必须 additionalProperties: false，禁止开放 patch、storePatch、executeScript、script 等任意 Store Patch 或代码入口。不得新增源码执行字段。
• 用户化描述只说明用途和影响，不写协议名、schema、revision、风险编号或开发解释。
• 输入和输出优先传 ApplicationRef；禁止传原始密钥、本地路径或不受控的大对象。
• 写能力必须绑定相关 scope revision；未知副作用的写操作禁止自动重放。

详细字段选择和范式见 references/capability-patterns.md。