痕迹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。

3. 绑定执行处理器

• 由所属功能模块注册处理器，不把新处理器继续堆进全局 command/query 执行表。
• 使用通用 capability 信封执行，禁止新增 kind: 'command'、kind: 'query'、HostCommand 或 HostQuery 分支。
• 执行前由统一入口校验版本、输入、权限与 expected revisions；执行后校验输出 schema 和成功证据。
• 关键链路在实际执行层记录 start、completed、failed，日志只记录稳定引用和脱敏信息。
• 页面尚未打开时也应能调用正式业务服务；确实依赖可视编辑器时，在 availability 和前置条件中明确声明。

4. 接入按需发现

• MCP 按授权返回稳定排序的声明目录，宿主未就绪时不隐藏静态工具；执行给出准确状态。Pi 按需披露同一目录，不能另写业务名单。

• 实体与属性约束只从真实注册表派生，模型猜测和当前页面不能隐藏已注册业务能力。

• 执行结果以真实输出、副作用、领域回读和持久化状态为依据；模型说明失败不能改写已经发生的业务事实。

• 幂等键按调用者隔离，执行前登记；未知结果先查询。取消等待不取消生成，保存恢复不重新执行业务动作。

• 为能力提供用户可能使用的中文、英文和领域别名。

• 声明 acceptsRefs、producesRefs 和前置依赖，让跨模块任务通过稳定引用衔接。

• Router 只提供页面锚点和搜索建议，不得以分类结果限制能力可用性或授权。

• 写能力必须通过 control.impacts 声明 Effect、实体和属性；一次输出可能影响多个目标时实现 resolveObservedEffects(input, output)，从真实结果解析数量、稳定引用和验证证据。没有解析器的能力一次最多贡献一个 Effect。

• 跨领域结果传递必须注册接收上游稳定引用的正式桥梁能力，并验证正式下游调用成功；禁止让模型猜测领域等价物、手工拼接内部路径，或把生成结果冒充素材。媒体 URL/本地路径只在宿主内部组合服务中流动。

• 反射层公开每个可写属性真实接受的 writeOperations；高层集合 set 由计划器确定性编译为 append/remove 最小差异，不支持的操作在计划期拒绝。

• 同一通用事务可以重复写同一属性，最终状态只验证最后一次写入；播放头、播放开关等会话控制声明 verificationStrategy: 'execution'，中间状态的真实领域副作用必须由正式结果测试覆盖。

• 后置步骤依赖前序步骤刚建立的动态可用状态时，静态权限仍在计划期拒绝，动态 availability 延迟到该步骤执行前复核，失败由事务补偿。

• entityType 与 target.kind 重复表达实体类型时由通用适配器统一规范化；领域 provider 只可在全局唯一时补全短引用，歧义引用继续拒绝。

• 写入触发自动创建/更新等领域级联副作用时，正式执行器必须返回带静态 declarationId 的强类型 Effect Receipt；evidence 只做验证与说明，禁止用它记账或只按输入猜影响范围。

• 拒绝必须能被自我修正：实体类型写错就列出该域注册了哪些，属性写错就列出这个实体有哪些，参数被静默丢弃就说清丢了哪些键与可用的是哪些。只给错误码等于逼模型继续猜，而它猜不中就是死循环。

• AI 可见输入 schema 不暴露 baseRevision / expectedRevisions。并发基线只由 Gateway expected-revision 信封传入，不得形成第二条 revision 路径。

5. 覆盖新功能

优先用通用动词覆盖（见第 0 节）；只有算法型语义操作才注册专用能力。

新增或修改下列对象时，注册能力或加入带原因的显式排除清单：

• 工作区、工具页、设置页和浮层。
• 工具箱工具和用户可触发的业务动作。
• 设置项及其读取、计划、提交能力。
• 生成记录、素材、项目、节点等用户可查询数据。
• 可在模块间传递的实体引用。
• 公开实体、属性、语义操作、验证方式和 Surface 观察策略；漏登记必须由 check:assistant-capabilities 或覆盖测试阻断。

不得因为“暂时没有助手需求”而省略覆盖判断。

6. 迁移旧工具

• 将旧 Agent 工具的 schema、权限、语义和执行行为迁入原生定义及模块处理器。
• 同一模块迁移完成后立即删除对应旧工具、HostCommand/HostQuery 分支和旧处理器，禁止保留双实现。
• 保留审批、revision、撤销、幂等、并发、脱敏和结果真实性语义。
• 删除被替代的执行入口和兼容描述生成器；本轮不制作旧工程、历史或账本的迁移器，以新建数据验收。

7. 验证

• 运行能力覆盖检查，确认定义、处理器、Surface、设置和工具覆盖一致。
• 新增或改造 Surface 时必须在统一目录声明观察提供者、捕获策略、数据等级、遮罩策略、支持模态、尺寸预算和失效条件；不允许留下无理由的观察空缺。
• 观察提供者、数据等级、遮罩策略和支持模态只在 resolveSurfaceObservationProfile 判断一次，目录和覆盖清单都从它派生；界面标注 Surface ID 时从目录反查，不在组件里复制映射表。
• 观察默认走 target="window" 整窗，任何时候都可用；只在需要聚焦时传具体 surfaceId。截图范围永远只有本应用窗口，禁止桌面和其他应用窗口。
• 遮罩只认显式的 data-observation-sensitive。新增界面时，凡是把明文本地路径、密钥或令牌渲染出来的节点都要自己标上；type="password" 的输入框自带圆点掩码，不需要标。
• observe_application_surface 是应用截图入口，原始媒体通过正式媒体读取入口取得。不要新增只返回媒体引用或“已截图”标记的观察能力——模型看不到画面却会以为看过了；要产生视觉证据就返回 verificationKind: 'visual_pending_model' 加合法附件。
• 空间类写入（三维、画布布局）必须配一个结构化验证能力，并通过正式调用读回验证；视觉证据是加成，不能替代结构化验证。
• 视觉观察优先使用领域结构化状态或稳定原生媒体，其次使用专用视口，最后才允许捕获已注册的应用内区域；禁止回退为系统桌面、其他窗口或整屏截图。
• 观察结果只有被主模型或观察模型实际读取后才能标记为视觉验证；只有结构化证据或模态不可用时必须分别标记，不能把媒体引用文本当作已读取内容。
• 为每项能力验证合法输入、非法输入、权限、revision 冲突、成功证据和失败恢复。
• 每个拥有 mutation/collection 执行器的写域登记 2–3 条结果场景；必须从正式状态源或 readEntity 断言世界真的变化，completed 或 evidence 不算结果断言。
• 涉及跨模块任务时验证稳定引用传递，不得通过名称猜测或原始路径衔接。
• 按 docs/rules/testing.md 确定最小匹配检查。涉及公共核心契约及关键依赖的整轮重构在最终集成做一次 L3，不在每次搬移后重复全量。
• 关键结论依赖 Electron 生命周期、桥接或渲染时，使用正式 test:reality 隔离场景，检查实际截图和日志；产物过期只需 electron:bundle。不得以浏览器代替 Electron。

完成标准

• 能做的事优先通过通用动词暴露；专用能力只用于无法用属性写入表达的算法型操作。

• 声明 collectionWrite 的实体类型都注册了 ApplicationCollectionExecutor，由覆盖测试拦截。

• 每个 provider 都实现动态集合可用性；模式限制可在 describe 阶段看见，并由事务引擎统一执行。

• 每个实体都有 mutation/collection 执行器或非敷衍的 writeExclusion.reason；新增实体后运行 npm run check:assistant-capabilities。

• Application Control 反射注册表是实体、属性和集合 CRUD 的唯一元数据源；ApplicationCapabilityDefinition 是算法操作的唯一元数据源；Pi 与 MCP 工具目录都只能投影两者，不能成为第三份手写 schema。

• 新增已登记的业务实体或属性后，外部智能体无需任何 MCP 侧改动即可读写；有意只读的实体带得住 writeExclusion.reason。

• 对外输入、输出和错误通过公共契约校验，并由固定现代协议的官方 Client 经 HTTP 验证。

• 正式业务服务是唯一业务执行源。

• 普通界面不显示开发性解释。

• 新代码没有旧 command/query 兼容路径。

• 新代码没有任意 Store Patch、任意脚本执行或 Application API 核心跨层导入。

• 权限、revision、日志、引用和成功证据均有自动化验证。

• 用户编辑 A 时可后台读改、生成并保存 B；打开 B 复用同一实例和历史，关闭页面不结束已提交工作。

• 保存失败保留脏状态；删除和退出经过实例屏障，只有已保存、无任务、无使用者时才释放。