evolcore 0.0.49 → 0.0.50

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (250) hide show
  1. package/CHANGELOG.md +64 -1
  2. package/bin/ecmsg.js +9 -4
  3. package/dist/ability/caller/authorization.js +21 -0
  4. package/dist/ability/caller/command.js +164 -0
  5. package/dist/ability/caller/contract.js +102 -0
  6. package/dist/ability/caller/daemon.js +158 -0
  7. package/dist/ability/caller/service.js +380 -0
  8. package/dist/ability/command-contract.js +5 -0
  9. package/dist/ability/daemon.js +5 -1
  10. package/dist/ability/interop-v1.js +10 -3
  11. package/dist/ability/management.js +1 -0
  12. package/dist/agent-template/jobs.js +173 -1
  13. package/dist/agent-template/runtime.js +280 -6
  14. package/dist/agent-template/service.js +1159 -40
  15. package/dist/agent-template/types.js +2 -1
  16. package/dist/agents/baseagent-availability.js +27 -3
  17. package/dist/agents/baseagent-capability-adapter.js +102 -0
  18. package/dist/agents/baseagent-plugin-descriptor.js +274 -0
  19. package/dist/agents/baseagent-plugin-loader.js +145 -0
  20. package/dist/agents/baseagent.js +68 -2
  21. package/dist/agents/claude-gateway/agent-registration.js +389 -0
  22. package/dist/agents/claude-gateway/binding.js +96 -0
  23. package/dist/agents/claude-gateway/inbox.js +138 -0
  24. package/dist/agents/claude-gateway/index.js +125 -0
  25. package/dist/agents/claude-gateway/listing.js +330 -0
  26. package/dist/agents/claude-gateway/router.js +328 -0
  27. package/dist/agents/claude-gateway/sessions.js +128 -0
  28. package/dist/agents/claude-gateway/terminal.js +250 -0
  29. package/dist/agents/claude-gateway/transcript.js +272 -0
  30. package/dist/agents/claude-gateway/types.js +14 -0
  31. package/dist/agents/claude-runner.js +6 -10
  32. package/dist/agents/codex-runner.js +4 -1
  33. package/dist/agents/{gemini-runner.js → gemini/gemini-runner.js} +17 -17
  34. package/dist/{core/session/adapters → agents/gemini}/gemini-session-file-adapter.js +2 -2
  35. package/dist/agents/gemini/index.js +51 -0
  36. package/dist/aun/aid/control-aid.js +52 -32
  37. package/dist/aun/group/invite-service.js +6 -36
  38. package/dist/aun/group/operations.js +6 -0
  39. package/dist/aun/msg/mention-schema.js +1 -1
  40. package/dist/aun/msg/p2p.js +29 -1
  41. package/dist/aun/msg/upload.js +126 -3
  42. package/dist/build-identity.json +1 -1
  43. package/dist/channels/aun.js +537 -189
  44. package/dist/cli/ability-command.js +42 -0
  45. package/dist/cli/agent-command.js +20 -1
  46. package/dist/cli/agent-create.js +78 -18
  47. package/dist/cli/agent-template.js +5 -3
  48. package/dist/cli/agent.js +91 -0
  49. package/dist/cli/aun-commands.js +92 -34
  50. package/dist/cli/bench.js +5 -2
  51. package/dist/cli/config.js +22 -6
  52. package/dist/cli/daemon-commands.js +245 -101
  53. package/dist/cli/ecmsg-gateway.js +11 -9
  54. package/dist/cli/index.js +23 -4
  55. package/dist/cli/init.js +39 -63
  56. package/dist/cli/managed-command-guard.js +1 -0
  57. package/dist/cli/menu-client.js +32 -7
  58. package/dist/cli/pay-command.js +30 -0
  59. package/dist/cli/provider-command.js +6 -2
  60. package/dist/cli/restart-monitor.js +2 -2
  61. package/dist/cli/services-command.js +11 -9
  62. package/dist/cli/thread-command.js +78 -12
  63. package/dist/config/access-policy.js +16 -3
  64. package/dist/config/config-field-policy.js +17 -8
  65. package/dist/config/config-manager.js +86 -46
  66. package/dist/config/config-operation-service.js +22 -1
  67. package/dist/config/gateway-config.js +9 -8
  68. package/dist/config/owner-config.js +0 -16
  69. package/dist/config/peer-role-resolver.js +1 -7
  70. package/dist/config/providers-config.js +99 -16
  71. package/dist/config/providers-management.js +35 -19
  72. package/dist/config/resolved-config-op.js +1 -42
  73. package/dist/config/schema-migration.js +78 -5
  74. package/dist/config/schema-registry.js +52 -7
  75. package/dist/config-store.js +1309 -17
  76. package/dist/core/agent-application-service.js +220 -1
  77. package/dist/core/agent-ipc-registration.js +19 -2
  78. package/dist/core/agent-reload-coordinator.js +5 -0
  79. package/dist/core/agent-runtime.js +198 -54
  80. package/dist/core/auth/agent-delegation.js +14 -0
  81. package/dist/core/auth/operation-authorizer.js +16 -1
  82. package/dist/core/auth/operation-catalog.js +50 -7
  83. package/dist/core/baseagent-loader.js +30 -3
  84. package/dist/core/capability/capability-manager.js +16 -7
  85. package/dist/core/channel-runtime.js +4 -2
  86. package/dist/core/command/agent-control.js +20 -2
  87. package/dist/core/command/agent-template-menu.js +4 -3
  88. package/dist/core/command/cli-intent-parser.js +15 -0
  89. package/dist/core/command/menu-catalog.js +20 -4
  90. package/dist/core/command/menu-file-path.js +70 -0
  91. package/dist/core/command/menu-handler.js +91 -72
  92. package/dist/core/command/menu-protocol.js +5 -0
  93. package/dist/core/command/menu-query-batch.js +2 -2
  94. package/dist/core/command/private-mention-menu.js +71 -0
  95. package/dist/core/command/slash-handler.js +17 -26
  96. package/dist/core/command/team-workspace-bootstrap.js +2 -1
  97. package/dist/core/command/topic-slash.js +7 -1
  98. package/dist/core/daemon-bootstrap.js +0 -4
  99. package/dist/core/daemon-control.js +2 -1
  100. package/dist/core/daemon-lifecycle.js +13 -5
  101. package/dist/core/evolagent-registry.js +12 -7
  102. package/dist/core/handoff/runtime.js +1 -1
  103. package/dist/core/host-snapshot.js +8 -3
  104. package/dist/core/initialization/service.js +3 -0
  105. package/dist/core/interaction-router.js +130 -0
  106. package/dist/core/ipc-registration.js +4 -0
  107. package/dist/core/memory/consolidation-context.js +2 -1
  108. package/dist/core/memory/consolidation.js +35 -64
  109. package/dist/core/message/aun-ipc-sender.js +98 -21
  110. package/dist/core/message/aun-request-registry.js +31 -0
  111. package/dist/core/message/message-bridge.js +105 -6
  112. package/dist/core/message/message-log.js +8 -0
  113. package/dist/core/message/message-queue.js +5 -3
  114. package/dist/core/message/peer-mode.js +15 -4
  115. package/dist/core/message/response-engine.js +23 -8
  116. package/dist/core/message/send-options.js +37 -3
  117. package/dist/core/message/send-routing.js +11 -7
  118. package/dist/core/model/model-catalog.js +5 -5
  119. package/dist/core/ownership/owner-resolver.js +12 -86
  120. package/dist/core/pack-auth.js +4 -0
  121. package/dist/core/permission/ec-command-parser.js +182 -58
  122. package/dist/core/permission/protected-paths.js +64 -9
  123. package/dist/core/permission/services-path-acl.js +9 -2
  124. package/dist/core/permission/tool-policy.js +21 -9
  125. package/dist/core/session/adapters/claude-session-file-adapter.js +6 -2
  126. package/dist/core/session/adapters/codex-session-file-adapter.js +4 -0
  127. package/dist/core/session/session-manager.js +47 -10
  128. package/dist/core/session/session-mapper.js +16 -0
  129. package/dist/core/skill/index-generator.js +2 -3
  130. package/dist/core/skill/switch-resolver.js +3 -0
  131. package/dist/core/thread/command-parser.js +4 -1
  132. package/dist/core/thread/ipc-operation.js +4 -2
  133. package/dist/core/thread/thread-operation.js +25 -10
  134. package/dist/core/thread/thread-service.js +294 -55
  135. package/dist/core/thread/topic-id.js +52 -2
  136. package/dist/core/thread/types.js +15 -1
  137. package/dist/eck/kit-renderer.js +2 -1
  138. package/dist/ecweb/basic-settings-service.js +5 -9
  139. package/dist/ecweb/providers-service.js +4 -2
  140. package/dist/index.js +116 -41
  141. package/dist/ipc.js +58 -2
  142. package/dist/paths.js +48 -1
  143. package/dist/pay/command.js +38 -0
  144. package/dist/pay/protocol.js +136 -0
  145. package/dist/pay/runtime.js +188 -0
  146. package/dist/pay/service.js +384 -0
  147. package/dist/pay/store.js +81 -0
  148. package/dist/response-system/engines/v1/proactive-flow.js +29 -2
  149. package/dist/services/dispatcher.js +23 -5
  150. package/dist/services/host/main.js +388 -0
  151. package/dist/services/host/protocol.js +118 -0
  152. package/dist/services/host/resident.js +310 -0
  153. package/dist/services/host-client.js +386 -0
  154. package/dist/services/host-deploy.js +180 -0
  155. package/dist/services/host-launch.js +117 -0
  156. package/dist/services/host-recycle.js +203 -0
  157. package/dist/services/host-runtime.js +802 -0
  158. package/dist/services/idempotency.js +44 -86
  159. package/dist/services/index-generator.js +4 -3
  160. package/dist/services/index.js +176 -18
  161. package/dist/services/ipc-operation.js +204 -44
  162. package/dist/services/script-runner.js +515 -83
  163. package/dist/services/validation.js +109 -4
  164. package/dist/trigger/application-service.js +6 -4
  165. package/dist/trigger/local-files.js +19 -9
  166. package/dist/trigger/scheduler.js +22 -12
  167. package/dist/trigger/script-sandbox.js +51 -20
  168. package/dist/utils/aid-bind.js +3 -0
  169. package/dist/utils/evolcore-version.js +2 -2
  170. package/dist/utils/host-info.js +73 -0
  171. package/dist/utils/logger.js +2 -2
  172. package/dist/utils/media-cache.js +190 -43
  173. package/dist/utils/restart-safety.js +14 -1
  174. package/dist/utils/system-memory.js +113 -25
  175. package/dist/utils/systemd-lifecycle.js +154 -0
  176. package/dist/utils/windows-shell-trust.js +7 -3
  177. package/kits/docs/INDEX.md +3 -2
  178. package/kits/docs/aun/AUN/346/266/210/346/201/257/347/261/273/345/236/213/344/270/216/345/261/236/346/200/247.md +1 -0
  179. package/kits/docs/channels/aun.md +1 -1
  180. package/kits/docs/evolcore/INDEX.md +7 -6
  181. package/kits/docs/evolcore/agent.md +36 -1
  182. package/kits/docs/evolcore/aid.md +20 -3
  183. package/kits/docs/evolcore/config.md +1 -1
  184. package/kits/docs/evolcore/group.md +2 -1
  185. package/kits/docs/evolcore/memory-tags.md +2 -0
  186. package/kits/docs/evolcore/menu-client.md +3 -3
  187. package/kits/docs/evolcore/menu-protocol.md +7 -0
  188. package/kits/docs/evolcore/model.md +3 -0
  189. package/kits/docs/evolcore/msg.md +68 -10
  190. package/kits/docs/evolcore/pay.md +34 -0
  191. package/kits/docs/evolcore/provider.md +21 -0
  192. package/kits/docs/evolcore/services.md +46 -18
  193. package/kits/docs/evolcore/thread-chain.md +2 -0
  194. package/kits/docs/evolcore/tool-authorization.md +10 -0
  195. package/kits/rules/01-overview.md +11 -32
  196. package/kits/rules/02-navigation.md +7 -0
  197. package/kits/rules/06-channel.md +3 -3
  198. package/kits/schemas/_meta.json +38 -5
  199. package/kits/schemas/agent-config.schema.21.json +974 -0
  200. package/kits/schemas/agent-config.schema.22.json +977 -0
  201. package/kits/schemas/agent-config.schema.23.json +958 -0
  202. package/kits/schemas/daemon.schema.10.json +373 -0
  203. package/kits/schemas/daemon.schema.9.json +12 -0
  204. package/kits/schemas/defaults.schema.7.json +472 -0
  205. package/kits/schemas/providers.schema.3.json +18 -2
  206. package/kits/schemas/relation-config.schema.13.json +289 -0
  207. package/kits/skills/.switches.json +13 -1
  208. package/kits/skills/ability/SKILL.md +229 -34
  209. package/kits/skills/ability/STRUCTURE.md +333 -0
  210. package/kits/skills/ability/references/cli.md +208 -0
  211. package/kits/skills/ability/references/development.md +107 -37
  212. package/kits/skills/ability/references/management.md +106 -46
  213. package/kits/skills/ability/references/runtime-protocol.md +65 -63
  214. package/kits/skills/agent-output-cards/SKILL.md +12 -5
  215. package/kits/skills/ec-group/SKILL.md +8 -6
  216. package/kits/skills/ec-group/TASK.md +186 -0
  217. package/kits/skills/ec-group/WORKLOG.md +180 -0
  218. package/kits/skills/ec-group-collaboration/SKILL.md +3 -3
  219. package/kits/skills/ec-pay/SKILL.md +101 -0
  220. package/kits/skills/ec-pay/references/pay-cli.md +110 -0
  221. package/kits/skills/ec-provider/SKILL.md +1 -1
  222. package/kits/skills/{ec-service-proxy → ec-proxy}/SKILL.md +8 -5
  223. package/kits/skills/ec-service-call/SKILL.md +135 -0
  224. package/kits/skills/ec-service-pack/SKILL.md +277 -0
  225. package/kits/skills/ec-trigger/SKILL.md +1 -1
  226. package/kits/templates/memory-consolidation/notes.md +2 -2
  227. package/kits/templates/memory-consolidation/workflow.md +46 -0
  228. package/kits/templates/system-fragments/channel.md +13 -4
  229. package/kits/templates/system-fragments/commands.md +4 -3
  230. package/kits/templates/system-fragments/reply.md +1 -0
  231. package/kits/templates/system-fragments/session.md +1 -1
  232. package/kits/templates/system-fragments/thread.md +27 -129
  233. package/kits/templates/system-fragments/venue.md +16 -0
  234. package/package.json +4 -5
  235. package/scripts/agent-template/inspect.mjs +37 -23
  236. package/scripts/agent-template/overlay.mjs +20 -2
  237. package/scripts/agent-template/shared/common.mjs +16 -4
  238. package/scripts/agent-template/shared/team-schema.json +20 -4
  239. package/scripts/agent-template/shared/template-contract.mjs +53 -13
  240. package/scripts/agent-template/shared/template-package.mjs +90 -26
  241. package/scripts/agent-template/shared/template-runtime.mjs +111 -1
  242. package/scripts/agent-template/shared/template.mjs +65 -7
  243. package/scripts/agent-template/team-pack.mjs +89 -33
  244. package/scripts/agent-template/team-preview.mjs +249 -5
  245. package/kits/docs/aun/ABILITY_CALLING.md +0 -280
  246. package/kits/docs/evolcore/ability.md +0 -185
  247. package/kits/skills/ability/references/calling.md +0 -56
  248. package/kits/skills/ability/references/contract-checklist.md +0 -37
  249. package/kits/skills/ability/references/recovery.md +0 -27
  250. /package/dist/{core/capability/providers → agents/gemini}/gemini-capability-provider.js +0 -0
@@ -1,58 +1,78 @@
1
- # EvolCore Ability 插件开发指南
1
+ # EvolCore 能力插件开发
2
2
 
3
- 本指南介绍 EvolCore 插件作为 AUN Ability Provider 实现的一种开发方式。AUN Ability 规范不要求所有 Provider 都使用 EvolCore 插件;选择实现时应以目标 AID 所在平台支持的接入方式为准。
3
+ EvolCore 插件只是 AUN Ability Provider 的一种实现方式。规范不要求所有 Provider 都用插件,
4
+ 选择实现时以目标 AID 所在平台支持的接入方式为准。
4
5
 
5
- 从 `ability` 技能进入开发阶段时读取。命令参数、语言矩阵和项目字段查 `$KITS_DOCS/evolcore/ability.md`“本地开发与打包”;Manifest/开发项目的精确字段用 `ec ability schema manifest/project` 查询。
6
+ 命令参数和语言矩阵读 [cli.md](cli.md);Manifest/项目字段用 `ec ability schema manifest/project`。
7
+ 交付安装、发布时接 [management.md](management.md)。纯开发不先查 daemon 或管理身份。
6
8
 
7
- ## 1. 确定需求与验收条件
9
+ ## 1. 定需求与验收条件
8
10
 
9
- 1. 把需求落实为明确输入、可验证输出、失败条件和副作用。区分用户只要设计、源码、发行包,还是希望安装到 AID 并发布。
10
- 2. 检查用户指定位置是否已有 ability-project.json、Manifest 或可复用实现,优先在原项目完善。
11
- 3. 确定插件 ID(@publisher/name)、版本、目标类型 agent/host/both、能力 path、handler 和资源需求。开发时选目标类型即可,具体安装 AID 在管理阶段解析。
12
- 4. 完成 [契约检查表](contract-checklist.md)。从生成的定义/usage 模板修改,遵循当前有限 Schema,不自行增加未支持的协议字段。
11
+ 1. 把需求落成明确输入、可验证输出、失败条件和副作用。分清用户只要设计、源码、发行包,
12
+ 还是希望装到 AID 并发布。
13
+ 2. 检查指定位置是否已有 `ability-project.json`、Manifest 或可复用实现,优先在原项目完善。
14
+ 3. 定插件 ID(`@publisher/name`)、版本、目标类型 `agent`/`host`/`both`、能力 path、handler、
15
+ 资源需求。开发时只需选目标类型,具体安装 AID 在管理阶段解析。
16
+ 4. 完成下方"实现前检查"清单。从生成的定义/usage 模板改,遵循当前有限 Schema,
17
+ 不自行增加未支持的协议字段。
13
18
 
14
- 纯开发不先查询 daemon 或管理身份。离线命令面可用 `ec ability dev --help`、`ec ability schema manifest`、`ec ability schema project` 查阅。
19
+ ## 2. 选语言
15
20
 
16
- ## 2. 根据现有环境选语言
21
+ 优先沿用现有实现和已配置环境:Node/Python 适合已有脚本;Java/Go/Rust 可复用原语言源码;
22
+ custom 用于已有预构建入口或明确的自定义构建命令。语言和版本矩阵读 [cli.md](cli.md),不在此重复。
17
23
 
18
- 优先沿用现有实现与已配置环境:Node/Python 适合已有脚本;Java/Go/Rust 可复用原语言源码;custom 用于已有预构建入口或明确的自定义构建命令。语言、编译器和运行时版本矩阵查命令手册,不在这里另行定义。
24
+ 用 `ec ability dev doctor --project <项目>` 检查实际环境,尚无项目时可加 `--language`。
25
+ 模板版本范围不替代目标环境验证;原生程序还依赖目标 OS 系统库。
26
+ 环境缺失或版本不符时报告具体项交用户准备;不自动安装工具、依赖或改 PATH。
19
27
 
20
- 用 `ec ability dev doctor --project <项目>` 检查实际开发环境,尚无项目时可按手册用 `--language`。模板版本范围不替代实际目标环境验证;原生程序还可能依赖目标 OS 的系统库。环境缺失或版本不符时报告具体项,由用户准备;不自动安装工具、依赖或修改 PATH。
28
+ 内置 builder 面向小型无第三方依赖项目;复杂工程由开发者提供显式构建 argv 或预构建产物。
29
+ 它不隐式调用 Maven、Gradle、Cargo、npm/pip install,也不自动打包依赖。
21
30
 
22
- 内置 builder 面向小型无第三方依赖项目;复杂工程由开发者提供显式构建 argv 或预构建产物。它不隐式调用 Maven、Gradle、Cargo、npm/pip install 或自动打包依赖。
23
-
24
- ## 3. 生成并理解项目
25
-
26
- 以下为可执行的 readiness 项目示例,每行独立执行。业务名称和语言按需求替换;init 只接受空目录。
31
+ ## 3. 生成项目
27
32
 
28
33
  ```text
29
34
  ec ability dev init './plugins/readiness' --id '@example/readiness' --name 'Readiness' --target agent --language python
30
35
  ec ability dev doctor --project './plugins/readiness'
31
36
  ```
32
37
 
33
- 生成目录结构和字段查命令手册及 `ec ability schema project`、`ec ability schema manifest`。在源码入口、definitions 与 usages 中实现业务;release/artifacts 是交付产物,不作为源码编辑位置。不要在 config 或 Manifest 中放秘密原文。
38
+ `init` 只接受空目录。目录结构和字段读 [cli.md](cli.md) 以及 `ec ability schema project`、
39
+ `ec ability schema manifest`。业务写在源码入口、definitions 和 usages 里;
40
+ `release/`、`artifacts/` 是交付产物,不是源码编辑位置。不在 config 或 Manifest 放秘密原文。
34
41
 
35
- build.sources 必须包含项目 entry 及所有辅助编译输入;files 只负责额外发行文件。Go 的 .go 文件由内置 builder 一起编译;Rust 以 sources 中第一个 .rs 文件为根入口,辅助模块也要声明并保持目录关系。
42
+ `build.sources` 必须包含项目 entry 和所有辅助编译输入;`files` 只负责额外发行文件。
43
+ Go 的 `.go` 文件由内置 builder 一起编译;Rust 以 sources 中第一个 `.rs` 为根入口,
44
+ 辅助模块也要声明并保持目录关系。
36
45
 
37
- 已有预构建入口可省略 build,让项目 entry 和 Manifest 的运行引用指向已有文件。Manifest runtime 的 entry 是发行入口,与开发项目的源码 entry 可不同。
46
+ 已有预构建入口可省略 build,让项目 entry 和 Manifest 的运行引用指向已有文件。
47
+ Manifest runtime 的 entry 是发行入口,可与开发项目的源码 entry 不同。
38
48
 
39
49
  ## 4. 实现能力与 Runner
40
50
 
41
- Node 模板 handler 默认导出 `async function (params, ctx)`;ctx 提供 config、caller、signal、幂等标识以及 host/storage/workspace/http/log 方法,具体映射见 [运行时协议](runtime-protocol.md)。开发工具将 handler 复制到 dist/handlers 并生成注册表,检查其他模块相对 import 是否仍然正确。
51
+ Node 模板 handler 默认导出 `async function (params, ctx)`;`ctx` 提供 config、caller、signal、
52
+ 幂等标识和 host/storage/workspace/http/log 方法,映射见 [runtime-protocol.md](runtime-protocol.md)。
53
+ 开发工具把 handler 复制到 `dist/handlers` 并生成注册表,检查其他模块的相对 import 是否仍正确。
42
54
 
43
- Python/Java/Go/Rust 模板只实现 getReadiness;要提供业务能力,修改原语言入口的 handler 分发和 initialize 返回集合。使用 Broker 时需自行实现反向请求关联和响应处理。模板没有完整的异步客户端、并发调度或数据迁移实现。
55
+ Python/Java/Go/Rust 模板只实现 getReadiness;要提供业务能力,改原语言入口的 handler 分发
56
+ 和 initialize 返回集合。用 Broker 时自行实现反向请求关联和响应处理。
57
+ 模板没有完整的异步客户端、并发调度或数据迁移实现。
44
58
 
45
59
  ```text
46
60
  ec ability dev add-ability 'example/status' --project './plugins/readiness' --handler getExampleStatus --name '示例状态'
47
61
  ```
48
62
 
49
- add-ability 生成契约、usage 和 pending 标记;Node 另生成 JS handler,非 Node 沿用原语言入口。完成实现、输入输出、effects、usage 和代码审查后,显式移除对应 pendingHandlers 项;不要只清空标记来让构建通过。若需要移除模板 self/status,先添加实际能力再使用 remove-ability,项目至少保留一项能力。
63
+ `add-ability` 生成契约、usage 和 pending 标记;Node 另生成 JS handler,非 Node 沿用原语言入口。
64
+ 完成实现、输入输出、effects、usage 和代码审查后,**显式移除对应的 `pendingHandlers` 项**;
65
+ 不要只清空标记来让构建通过。要移除模板的 self/status,先加实际能力再用 `remove-ability`,
66
+ 项目至少保留一项能力。
50
67
 
51
- 设计重试、超时和幂等:下游副作用使用宿主给出的 idempotencyKey,结果未知时先查原执行。遵守配置和资源授权边界;不让源码依赖开发目录、交互 stdin、隐藏环境变量或本机秘密。进程 cwd 是临时工作区,包资源以入口自身位置解析。
68
+ 设计重试、超时和幂等:下游副作用用宿主给的 `idempotencyKey`,结果未知时先查原执行。
69
+ 遵守配置和资源授权边界;不让源码依赖开发目录、交互 stdin、隐藏环境变量或本机秘密。
70
+ 进程 cwd 是临时工作区,包资源按入口自身位置解析。
52
71
 
53
- 自定义 runtime.command 是 argv,包内文件用 package: 引用。可只填 language + entry 使用默认启动,也可明确选择已有虚拟环境/JVM 参数。协议和具体配置见运行时指南。
72
+ 自定义 `runtime.command` 是 argv,包内文件用 `package:` 引用。
73
+ 可只填 language + entry 用默认启动,也可明确指定虚拟环境/JVM 参数。
54
74
 
55
- ## 5. 构建、校验与打包
75
+ ## 5. 构建、校验、打包
56
76
 
57
77
  ```text
58
78
  ec ability dev build --project './plugins/readiness'
@@ -60,21 +80,71 @@ ec ability dev check './plugins/readiness/release'
60
80
  ec ability dev pack --project './plugins/readiness'
61
81
  ```
62
82
 
63
- build 将声明的编译输入复制到当前会话 TMPDIR 的源码快照,在独立临时目录编译;只有 build.output 指定的单个文件复制进发行目录,编译附属文件不自动打包。Python 的辅助模块和其他运行资源需显式加入 files 并保持相对路径。
83
+ `build` 把声明的编译输入复制到当前会话 `$TMPDIR` 的源码快照,在独立临时目录编译;
84
+ 只有 `build.output` 指定的单个文件进发行目录,编译附属文件不自动打包。
85
+ Python 辅助模块和其他运行资源要显式加入 `files` 并保持相对路径。
86
+
87
+ custom builder 用 `kind=command` 的 argv,`{project}` 和 `{output}` 分别替换为源码快照和
88
+ 编译目标绝对路径;不支持 shell 拼接或子串替换。构建脚本也须加入 sources。
89
+ 编译器及显式构建命令是可信本地代码,没有 OS 沙箱或网络隔离保证;
90
+ EvolCore 不替这些命令准备环境。
91
+
92
+ 审查最终文件清单,确认没有凭据、开发私密文件或未声明产物。源码/版本变化后重新 build;
93
+ 手改 release 会拒绝打包。重复构建只替换原回执绑定且未变更的旧输出,未知目录不覆盖。
94
+ 包和归档限 32 MiB。
95
+
96
+ `dev check` 复用生产包格式/契约校验,不启动 Runner、不验证业务正确性。
97
+ `pack` 返回 `artifact`、`artifactDigest`、`packageDigest`,不上传、不安装、不发布。
98
+ `doctor` 只检测已有工具,`available:false` 时 exit 1;能检出工具不代表链接器、原生依赖或业务可用。
99
+
100
+ ## 6. 验证与交接
101
+
102
+ 1. 用独立业务测试验证正常/边界输入、数值精度、输出结构、依赖不可用和幂等行为;
103
+ 只执行已授权测试,不用真实业务写入作默认验收。
104
+ 2. 用户要求安装/使用/发布时,带实际产物进 [management.md](management.md),
105
+ 再解析目标 AID,复用 preview/install/enable/invoke 验证。当前没有独立 `dev test` 运行器。
106
+ 3. 记录项目路径、语言、插件 ID/版本、paths/handlers、归档路径、摘要、所需配置/资源和验证结果;
107
+ 部署环境未验证的部分明确标注。
108
+ 4. 改已安装版本时用 `ec ability dev version <major.minor.patch> --project <project>`
109
+ 后重新 build/pack,交 management 的 preview/upgrade;开发版本命令不改已安装实例。
110
+
111
+ **源码就绪 / 契约检查 / 实际业务结果 / 本地管理 / 外部 AUN Caller 验证** 分别报告。
112
+ 只完成开发时不得声称能力已安装或上架。
113
+
114
+ ## 实现前检查
115
+
116
+ 开始实现前逐项确定;不适用的项也要说明原因。
117
+
118
+ **能力定义**
64
119
 
65
- custom builder 使用 kind=command 的 argv,完整参数 {project} 和 {output} 分别替换为源码快照和编译目标绝对路径;不支持 shell 拼接或子串替换。构建脚本也须加入 sources。编译器及显式构建命令是可信本地代码,没有 OS 沙箱或网络隔离保证;EvolCore 本身不替这些命令准备环境。
120
+ - [ ] 唯一稳定的 ability path,以及清晰的名称、用途和限制
121
+ - [ ] params schema 定义类型、必填、边界、默认值和拒绝策略
122
+ - [ ] result schema 定义成功、空结果和稳定错误码;不暴露凭据或无关个人数据
123
+ - [ ] usage 描述调用前提、示例、效果、失败和结果解释
66
124
 
67
- Java 使用 --release 17 生成 JAR;需要更新 Java 特性时改用显式构建并同步 engines.java。Go 关闭代理、自动工具链下载和 CGO。Rust 优化编译,Windows 增加静态 CRT 参数;目标系统库仍需验证。Go/Rust 构建锁定当前 OS/CPU,省略 build 的预构建原生包需自行正确填写 platforms/architectures,custom 新模板默认仅支持本机 OS/CPU。
125
+ **权限与副作用**
68
126
 
69
- 审查最终文件清单和内容,确认没有凭据、开发私密文件或未声明产物。源码/版本变化后重新 build,pack 对旧回执返回 BUILD_STALE;手改 release 也会拒绝打包。重复构建只替换原回执绑定且未变更的旧输出,未知目录不覆盖。包和归档沿用 32 MiB 限制。
127
+ - [ ] 明确运行于 agent、host 或两者,以及实际需要的资源
128
+ - [ ] 遵循最小权限;秘密不进入 manifest、源码、参数或日志
129
+ - [ ] 写入、删除、联系第三方或产生费用时,明确 `effects`、认证和逐次确认
130
+ - [ ] 定义幂等键和重试行为;不确定前次结果时不盲目重放非幂等操作
131
+ - [ ] 只有确实需要外部授权时才设计 grant,并限定主体、资源和操作范围
70
132
 
71
- dev check 复用生产包格式/契约校验,不启动 Runner,不验证业务正确性。pack 返回 artifact、artifactDigest、packageDigest,不上传、不安装、不发布。doctor 只检测已有工具,available:false 时 exit 1;能检测版本不代表链接器、原生依赖或业务一定可用。
133
+ **实现与验证**
72
134
 
73
- ## 6. 验证与衔接管理
135
+ - [ ] 已选语言并记录构建/运行环境、版本和目标 OS/CPU;缺失环境不自动安装
136
+ - [ ] Manifest runtime 指向真实发行入口;开发 entry/build.sources/files 与实际源码一致
137
+ - [ ] 非 Node Runner 实现所需生命周期和 handler 分发,initialize 集合与 Manifest 一致;
138
+ stdout 只输出协议
139
+ - [ ] handler 对无效输入和依赖不可用返回稳定错误,不用成功形状伪装失败
140
+ - [ ] 处理超时、重复请求和并发边界;不在调用方无法审计的位置写隐式状态
141
+ - [ ] `pendingHandlers` 为空,源码、声明、用法和打包清单一致
142
+ - [ ] 已检查发行文件清单,不含凭据、测试数据或开发期文件
143
+ - [ ] 记录实际验证层级:构建/契约检查、授权目标业务执行、外部 AUN Caller 验收
74
144
 
75
- 1. 用独立业务测试验证正常/边界输入、数值精度、输出结构、依赖不可用和幂等行为;只执行已授权测试,不使用真实业务写入作默认验收。
76
- 2. 用户要求安装/使用/发布时,带着实际产物进入 [管理指南](management.md),再解析目标 AID,复用 preview/install/enable/invoke 验证。当前没有独立 dev test 运行器。
77
- 3. 记录项目路径、语言、插件 ID/版本、paths/handlers、归档路径、摘要、所需配置/资源和验证结果;部署环境未验证的部分明确标注。
78
- 4. 修改已安装版本时用 `ec ability dev version <major.minor.patch> --project <project>` 后重新 build/pack,交管理流程 preview/upgrade;开发版本命令不改变已安装实例。
145
+ **交接**
79
146
 
80
- 源码 readiness、契约检查、实际业务结果、本地管理和外部 AUN Caller 验证分别报告。只完成开发时不得声称能力已经安装或上架。
147
+ - [ ] 交付实际发行目录或 tgz、`packageDigest`/`artifactDigest`、插件 ID/版本和能力路径
148
+ - [ ] 说明配置、秘密槽、Manifest 资源需求和所需 Grant;不把声明当成已授权
149
+ - [ ] 进入安装或发布时再核实可信目标 AID、当前 revision 和实际批准;
150
+ 只开发时明确尚未安装/发布
@@ -1,12 +1,17 @@
1
- # 能力插件管理指南
1
+ # 能力插件管理
2
2
 
3
- 开发任务交付安装、使用或发布时,从这里继续;已有包或实例直接进入对应阶段。只调用已有本地实例时,从第 1 节核实目标后直接进入第 5 节,不重走安装/发布。命令每行独立执行,示例中的路径、ID 和 JSON 文件均替换为实际值。完整参数以 `$KITS_DOCS/evolcore/ability.md`、当前 CLI help/Schema 和 daemon capabilities 为准。
3
+ 把已打好包的插件装到某个 AID 上,配置、授权、发布、升级、下架。
4
+ 开发阶段读 [development.md](development.md);命令语法读 [cli.md](cli.md);远端调用见 [SKILL.md](../SKILL.md)。
4
5
 
5
- ## 1. 核实目标、现有实例与权限
6
+ 只调用已有本地实例时,从第 1 节核实目标后直接跳到第 5 节,不重走安装和发布。
7
+ 每行 `ec` 命令单独执行,示例里的路径、ID、JSON 都换成实际值。
6
8
 
7
- 1. 用户说“给你/当前 Agent 增加能力”时,使用当前可信 self;用户明确指定其他 AID 时按授权使用该目标。host 与 agent 是不同目标类型,不能用 Owner AID 或目录名猜测安装位置。
8
- 2. 执行以下查询,明确认证来源、目标类型和实际获准动作。显式目标用 --aid <AID> 替代 --self,两者互斥。
9
- 3. 优先复用现有实例和项目。检查 show/status/doctor 及当前版本、paths、配置和 Grant,不重复安装或发布。
9
+ ## 1. 核实目标与现状
10
+
11
+ 1. 用户说"给你/当前 Agent 加能力"用当前可信 self;明确指定其他 AID 时按授权用该目标。
12
+ host 与 agent 是不同目标类型,不能用 Owner AID 或目录名猜安装位置。
13
+ 2. 先查认证来源、目标类型和实际获准动作。显式目标用 `--aid <AID>` 替代 `--self`,两者互斥。
14
+ 3. 优先复用现有实例和项目:查 show/status/doctor、版本、paths、配置和 Grant,不重复安装或发布。
10
15
 
11
16
  ```text
12
17
  ec ability capabilities --format json
@@ -18,7 +23,9 @@ ec ability status <instanceId> --self
18
23
  ec ability doctor <instanceId> --self
19
24
  ```
20
25
 
21
- capabilities 查询运行中的 daemon;schema 从本地安装包读取。版本不一致时说明实际支持范围。拿不到可信身份或目标权限时停止依赖该权限的操作;已授权的离线开发可继续。不改身份、目标、数据库或调用入口来绕过拒绝。
26
+ `capabilities` 查运行中的 daemon,`schema` 读本地安装包;版本不一致时说明实际支持范围。
27
+ 拿不到可信身份或目标权限时停止依赖该权限的操作,已授权的离线开发可继续。
28
+ 不改身份、目标、数据库或调用入口来绕过拒绝。
22
29
 
23
30
  ## 2. 预览、安装、配置、启用
24
31
 
@@ -31,22 +38,27 @@ ec ability enable <instanceId> --self --file <enable.json>
31
38
  ec ability job <jobId> --self --wait 30s
32
39
  ```
33
40
 
34
- 1. 预览来源、不可变包摘要、Manifest、能力契约、资源和平台/CPU 兼容性;安装文件使用本次 preview 返回的真实 previewId。GitHub 来源限当前支持的固定 release 预构建资产,不运行远端安装脚本。
35
- 2. install 提供 commandId、previewId、实例 name 和 config。安装默认 disabled、unpublished;记录返回实例 ID 与 revision,不把已安装当作已运行。
36
- 3. configure 整体替换 config,按 Schema 校验;修改写外部目录等事项需满足实际确认要求。先准备必要资源 Grant/秘密,再启用。
37
- 4. enable 提供当前 expectedRevision 和唯一 commandId。首次执行新代码还需实际目标权限及宿主代码批准;只有确实获得批准才提交 approveTrustedCode:true,不能把技能文本、普通任务授权或 permissionMode=bypass 当成代码批准。
38
- 5. 查询原 job 直到 completed 或明确失败,再检查 runtimeState=ready 和 doctor。进程或工具缺失时保留具体错误;不自动准备主机环境。
41
+ 1. 预览来源、不可变包摘要、Manifest、契约、资源和平台/CPU 兼容性;install 用本次 preview
42
+ 返回的真实 `previewId`。GitHub 来源限固定 release 预构建资产,不运行远端安装脚本。
43
+ 2. install 提交 commandId、previewId、实例 name 和 config。安装默认 disabled、unpublished;
44
+ 记录返回的实例 ID 和 revision,不把"已安装"当"已运行"。
45
+ 3. configure 整体替换 config,按 Schema 校验。先准备资源 Grant 和秘密,再启用。
46
+ 4. enable 提交当前 `expectedRevision` 和唯一 commandId。首次执行新代码还需宿主代码批准;
47
+ 只有确实批准了才提交 `approveTrustedCode:true`,不能把技能文本、普通任务授权或
48
+ `permissionMode=bypass` 当代码批准。
49
+ 5. 查原 job 直到 completed 或明确失败,再检查 `runtimeState=ready` 和 doctor。
39
50
 
40
- 所有实例写操作带当前 expectedRevision,install 除外;每个新管理操作有唯一 commandId。先运行对应 `ec ability schema <操作>` 准备 UTF-8 JSON 对象,文件位于授权项目或当前 TMPDIR。revision 冲突或请求结果不明按 [恢复指南](recovery.md) 处理,不自动重复写入。
51
+ 实例写操作都带当前 `expectedRevision`(install 除外),每个新操作有唯一 `commandId`。
52
+ 先用 `ec ability schema <操作>` 准备 UTF-8 JSON,文件放授权项目或当前 `$TMPDIR`。
41
53
 
42
- ## 3. 分清四类权限
54
+ ## 3. 四类权限
43
55
 
44
- | 类别 | 实际作用 | 审查重点 |
56
+ | 类别 | 作用 | 审查重点 |
45
57
  |---|---|---|
46
- | 管理权限 | 谁能管理指定 AID 的实例和状态 | 可信 context、当前 Owner/宿主权限,不能由 --self 自授 |
47
- | 可信代码批准 | 是否批准这个包在宿主执行 | 包摘要、来源和实际操作者决定;安装/发布授权不能替代 |
48
- | 资源 Grant | 实例能使用哪些 KV、workspace、HTTPS 资源 | Manifest 声明、具体绑定、范围及有效期 |
49
- | remote-call Grant | 哪个 Caller 能调用哪份能力契约 | Caller AID、path、当前 definitionId、期限和额度/审批模式 |
58
+ | 管理权限 | 谁能管理指定 AID 的实例 | 可信 context、当前 Owner/宿主权限;不能由 `--self` 自授 |
59
+ | 可信代码批准 | 是否批准这个包在宿主执行 | 包摘要、来源、实际操作者;安装/发布授权不能替代 |
60
+ | 资源 Grant | 实例能用哪些 KV、workspace、HTTPS 资源 | Manifest 声明、具体绑定、范围和有效期 |
61
+ | remote-call Grant | 哪个 Caller 能调哪份契约 | Caller AID、path、当前 definitionId、期限、额度/审批模式 |
50
62
 
51
63
  ```text
52
64
  ec ability schema grant
@@ -54,33 +66,45 @@ ec ability grant <instanceId> --self --file <grant.json>
54
66
  ec ability approvals --self
55
67
  ```
56
68
 
57
- grant JSON 带 commandId/expectedRevision,按用户明确授权的资源或 Caller 范围准备。新增 Grant 的 expiresAt 是未来 Unix 毫秒时间戳,当前要求最长一年;从当前时间计算,不能把过期或示例时间戳照抄为实际授权。
69
+ grant JSON 带 commandId/expectedRevision,按用户明确授权的范围准备。
70
+ `expiresAt` 是未来 Unix 毫秒时间戳,当前最长一年;从当前时间算,不能照抄示例。
58
71
 
59
- | permission | value 的主要字段 |
72
+ | permission | value 主要字段 |
60
73
  |---|---|
61
- | storage | 可用空对象授权本实例私有 KV,不扩展为其他实例或 AID 的数据访问 |
62
- | workspace | root 为已存在的授权绝对目录,mode 为 read 或 read-write;受 Manifest workspace 限制 |
63
- | http | origin 为 Manifest 声明的 HTTPS origin;可有仅限该 origin 的 secretSlots |
64
- | remote-call | callerAid、path、从当前实例取得的 definitionId;可有 mode、paramsSchema、maxCalls、budgets |
74
+ | storage | 空对象即授权本实例私有 KV,不扩展到其他实例或 AID |
75
+ | workspace | `root` 为已存在的授权绝对目录,`mode` 为 read 或 read-write;受 Manifest 限制 |
76
+ | http | `origin` 为 Manifest 声明的 HTTPS origin;可有仅限该 origin 的 `secretSlots` |
77
+ | remote-call | `callerAid`、`path`、当前实例的 `definitionId`;可有 mode、paramsSchema、maxCalls、budgets |
65
78
 
66
- 当前 remote-call 模式:persistent 在期限/额度内持续生效;once 仅准入一次新执行;approval 为每个操作进入审批队列。paramsSchema 限定参数范围,maxCalls 限定新执行次数,budgets 只累计声明过的顶层非负整数参数。
79
+ remote-call 模式:`persistent` 在期限/额度内持续生效;`once` 只准入一次新执行;
80
+ `approval` 每个操作进审批队列。`paramsSchema` 限定参数范围,`maxCalls` 限定新执行次数,
81
+ `budgets` 只累计声明过的顶层非负整数参数。
67
82
 
68
- 新增 remote-call Grant 还须提交 confirmed:true,明确确认 Caller、能力路径与当前不可变契约;不要使用旧 definitionId 或用发布动作替代这项确认。
83
+ 新增 remote-call Grant 还须 `confirmed:true`,明确确认 Caller、路径和当前不可变契约;
84
+ 不用旧 definitionId,也不用发布动作替代这项确认。
69
85
 
70
- approval 模式当前通过 approvals 查看待决请求,再用 grant 的 approvalId 与 decision=approved/denied 处理。批准本身不执行业务;Caller 须沿用原 operationId、契约和参数,以新的传输请求重试。当前审批记录有效期 10 分钟。Owner 私聊卡片、120 秒同步等待和长窗口迟到批复是后续设计,不写成已支持流程。
86
+ `approval` 模式通过 `approvals` 看待决请求,再用 grant 的 `approvalId` 和
87
+ `decision=approved/denied` 处理。批准不执行业务;Caller 须沿用原 operationId、契约和参数
88
+ 发新请求。审批记录有效期 10 分钟。
71
89
 
72
- 撤销指定 Grant 使用实际 revokeId;变更 workspace/http 资源绑定可能改变契约语义和 definitionId,随后重新读取 show/status,检查既有发布与 Caller Grant 是否需重建。Grant 不因复制旧 JSON、切换 AID 或改 display name 自动恢复有效。
90
+ 撤销 Grant 用实际 `revokeId`。变更 workspace/http 绑定可能改变契约语义和 definitionId,
91
+ 之后要重读 show/status,检查发布与 Caller Grant 是否需重建。Grant 不会因复制旧 JSON、
92
+ 换 AID 或改 display name 自动恢复。
73
93
 
74
- ## 4. 秘密与资源准备
94
+ ## 4. 秘密与资源
75
95
 
76
96
  ```text
77
97
  ec ability schema secrets
78
98
  ec ability secrets <instanceId> --self --slot <slot> --revision <N> --command-id <ID> --stdin
79
99
  ```
80
100
 
81
- 秘密只经独立非交互 stdin 写入,不放在 JSON 参数文件、argv、源码或日志中,不回显。使用工具支持的非交互输入方式;不要为了传秘密拼接多个 ec 命令。后端不可用时报告并停止该依赖阶段,不使用明文替代。写外部目录涉及的 acknowledgeExternalData / --acknowledge-external-data 按相应命令实际 Schema/help 处理。
101
+ 秘密只经独立非交互 stdin 写入,不放进 JSON、argv、源码或日志,不回显。
102
+ 不为传秘密拼接多条 ec 命令。后端不可用时报告并停止,不用明文替代。
103
+ 写外部目录的 `--acknowledge-external-data` 按实际 Schema 处理。
82
104
 
83
- workspace 与 HTTP Grant 都必须落在 Manifest 声明范围;HTTP secretSlots 仅引用已配置槽,不把秘密交给 Runner。资源授权、业务确认及 Caller 授权分别设置,避免把授权一个能力扩展为授权整个 AID 的其他操作。
105
+ workspace 和 HTTP Grant 都必须落在 Manifest 声明范围内;HTTP `secretSlots` 只引用已配置槽,
106
+ 不把秘密交给 Runner。资源授权、业务确认、Caller 授权分别设置,
107
+ 避免把授权一个能力变成授权整个 AID 的其他操作。
84
108
 
85
109
  ## 5. 调用验证与发布
86
110
 
@@ -92,26 +116,62 @@ ec ability publish <instanceId> --self --file <publish.json>
92
116
  ec ability status <instanceId> --self --wait-publication 30s
93
117
  ```
94
118
 
95
- invoke 文件使用当前 path/definitionId、符合契约的 params、confirmed:true、新业务 operationId,以及 commandId/expectedRevision。本地确认调用不创建远端 Caller Grant。选择独立测试数据和用户已授权场景,验证真实结果;不要为“冒烟”擅自执行写入、费用或外部联系。管理 job 完成后还要核实 invocation.state、ok 和实际业务输出;结果披露另受本地 result-read 或远端当前 Caller 授权约束。
119
+ invoke 文件用当前 path/definitionId、符合契约的 params、`confirmed:true`、新业务 operationId、
120
+ commandId 和 expectedRevision。本地确认调用不创建远端 Caller Grant。
121
+ 用独立测试数据和已授权场景验证真实结果;不为"冒烟"擅自执行写入、费用或外部联系。
122
+ 管理 job 完成后还要核实 `invocation.state`、`ok` 和实际业务输出;结果披露另受授权约束。
96
123
 
97
- publish 的 paths 是整体替换集合,从当前实例读取精确路径。先确保 Runner ready,再提交所需 paths,查询原 job,等待 publicationConverged:true。已受理、任务完成、本地 ready、公开索引收敛分别检查。
124
+ publish 的 `paths` 是整体替换集合,从当前实例读精确路径。先确保 Runner ready,
125
+ 再提交 paths、查原 job、等 `publicationConverged:true`。
126
+ **已受理 / 作业完成 / 本地 ready / 公开索引收敛** 分别检查。
98
127
 
99
- 发布不自动允许所有 Caller。需要时按第 3 节授权用户指定的 Caller;外部发现/调用衔接同一技能的[调用指南](calling.md),由获授权的调用方验收,不把本地 invoke 当成真实 AUN 互通证据。
128
+ 发布不自动允许所有 Caller。需要时按第 3 节给指定 Caller 授权;
129
+ 外部验收按 [SKILL.md](../SKILL.md)“一、调用别人的能力”,不把本地 invoke 当真实 AUN 互通证据。
100
130
 
101
- ## 6. 下架、停用、卸载与版本维护
131
+ ## 6. 下架、停用、卸载、版本维护
102
132
 
103
133
  | 需求 | 动作 | 完成后检查 |
104
134
  |---|---|---|
105
135
  | 全部下架 | unpublish | 发布收敛为已确认 unpublished;本地实例仍在 |
106
136
  | 部分下架 | publish 提交剩余 paths | 核对剩余发布集合及收敛 |
107
137
  | 停止运行 | disable | desired/runtime 状态和进程;已有发布可能降级 |
108
- | 删除本地实例 | uninstall | 实例退出管理列表;历史/去重回执不等于自动清空 |
109
- | 升级包 | preview 传当前 instanceId,再 upgrade | 来源、摘要、差异、revision、配置、实际代码批准与激活结果 |
110
- | 回滚 | rollback 指定实际 generation | 对应包/配置/管理数据恢复与当前授权/发布状态 |
111
- | 淘汰回滚点 | retire 指定实际 generation | 不再作为可用回滚点,不等于卸载当前实例 |
112
-
113
- unpublish/disable/uninstall 使用各自命令和当前 revision,不能互相替代。不同动作的授权范围按用户目标决定。
114
-
115
- 升级前审查当前 history、preview 差异、兼容性/来源变化、降级、迁移和外部数据影响,按 Schema 提交实际必要批准;不同包内容要更新版本。回滚不能假定外部工作目录和第三方系统数据同步恢复,提前明确备份范围。新版本失败后检查旧实例恢复结果,禁止循环强制升级或无条件重复业务。
116
-
117
- 每阶段记录 Provider AID、实例 ID、revision、commandId/jobId 和结果;结束时按主技能的交付表报告真实状态。失败、未批准、发布待收敛或未做外部验收时明确标注。
138
+ | 删除本地实例 | uninstall | 实例退出列表;历史/去重回执不等于清空 |
139
+ | 升级 | preview 传 instanceId,再 upgrade | 来源、摘要、差异、revision、配置、代码批准、激活结果 |
140
+ | 回滚 | rollback 指定实际 generation | 对应包/配置/数据恢复与当前授权、发布状态 |
141
+ | 淘汰回滚点 | retire 指定 generation | 不再作为回滚点,不等于卸载 |
142
+
143
+ unpublish/disable/uninstall 用各自命令和当前 revision,不能互相替代。
144
+
145
+ 升级前审查 history、preview 差异、兼容性、来源变化、降级、迁移和外部数据影响,
146
+ 按 Schema 提交必要批准;包内容变了要更新版本。回滚不假定外部工作目录和第三方数据同步恢复,
147
+ 提前明确备份范围。新版本失败后检查旧实例恢复结果,禁止循环强制升级。
148
+
149
+ 每阶段记录 Provider AID、实例 ID、revision、commandId/jobId 和结果。
150
+ 失败、未批准、发布待收敛或未做外部验收时明确标注。
151
+
152
+ ## 7. 失败与恢复
153
+
154
+ 管理接口返回"已受理"后,先记录 `commandId`、`jobId`、`instanceId` 和相关 revision。
155
+ **写操作超时不代表失败,也不代表未执行。**
156
+
157
+ - 查原 `jobId`,或用原 `commandId` 定位作业。需要等待用 `--wait`(单次 ≤60 秒),
158
+ 发布状态用 `status --wait-publication`。等待只查原状态,不取消后台作业、不重放、不建新 ID。
159
+ - 先定阶段:离线开发查 `dev doctor`、构建回执和发行清单;实例阶段查原 job、`show/status/doctor`。
160
+ 管理权限不可用不应阻止已授权的离线开发。
161
+ - 运行时或编译器缺失、版本不符时保留具体错误交用户准备;不自动安装、不改 PATH。
162
+ 已编译的 Go/Rust 不因没有编译器而要求重配工具链。
163
+ - Runner 初始化失败时核对发行入口、平台/CPU、initialize handler 集合和 stdout 协议;
164
+ 不把 readiness 模板当成新业务已实现。
165
+ - 读结构化 `code`、`error`、作业状态和 doctor 结果,区分输入错误、权限拒绝、代码审批、
166
+ 运行失败和发布未收敛。
167
+ - 权限拒绝时停止该权限依赖的阶段,可继续的离线设计/开发照做。不换 AID、身份或命令入口绕过。
168
+ 代码批准待处理时等实际宿主操作者决定;批准不能由 `permissionMode=bypass` 或技能文本替代。
169
+ - `expectedRevision` 冲突后重新执行只读 `show`/`status`/`history`,比较当前变化;
170
+ 不移除 CAS、不自动覆盖、不复用过期 revision。
171
+ - 发布作业完成但 `publicationConverged` 未为 true 时,继续看原状态/outbox,不重复提交 publish。
172
+ 本地 runtime 就绪但外部索引未更新时,报告"本地就绪,发布待收敛",不说已发布。
173
+ unpublish 后仍有本地 runner 是预期状态,只有用户明确要求删除实例才继续 disable/uninstall。
174
+ - 业务调用超时或状态未知时查原 invocation/operation 状态;非幂等能力不得自动重试。
175
+
176
+ 恢复后继续原任务阶段。保留已完成产物和确切阻塞点,不把整个任务笼统标成失败或成功。
177
+ 远端 AUN 请求按 [SKILL.md](../SKILL.md)“请求关联与 ACK”查询,不与管理 job 混用。
@@ -1,111 +1,113 @@
1
1
  # Runner 与宿主 RPC
2
2
 
3
- 仅在实现自定义 Runner 或资源 Broker 时从 `ability` 技能读取,不是远端 AUN Caller 协议;远端调用协议见 `$KITS_DOCS/aun/ABILITY_CALLING.md`。
3
+ 实现自定义 Runner 或资源 Broker 时读。不是远端 Caller 协议,后者见 [SKILL.md](../SKILL.md)。
4
4
 
5
- ## 1. 选择运行方式
5
+ ## 运行方式
6
6
 
7
- Node 默认项目使用 node-subprocess:插件入口导出对象,宿主 adapter 完成协议、handler 分发和 Broker 调用。Python、Java、Go、Rust、custom 使用 process-rpc,Runner 自己读写 stdin/stdout 帧。Node 也可选 process-rpc,但需要自行实现同一协议。
7
+ Node 默认用 node-subprocess:插件入口导出对象,宿主 adapter 完成协议、handler 分发和 Broker 调用。
8
+ Python、Java、Go、Rust、custom 用 process-rpc,Runner 自己读写 stdin/stdout 帧。
9
+ Node 也可选 process-rpc,但要自行实现同一协议。
8
10
 
9
- 优先用 dev init 生成当前安装包模板,再修改业务逻辑。随包模板位于 [ability-templates](../../../runtime/ability-templates/);Node adapter 位于 [ability-runner.mjs](../../../runtime/ability-runner.mjs)。它们是具体行为依据,模板不等于完整 SDK。
11
+ 优先用 `dev init` 生成模板再改业务逻辑。随包模板在 [ability-templates](../../../runtime/ability-templates/),
12
+ Node adapter 在 [ability-runner.mjs](../../../runtime/ability-runner.mjs)。它们是行为依据,不等于完整 SDK。
10
13
 
11
- ## 2. Manifest 入口
14
+ ## Manifest 入口
12
15
 
13
- process-rpc 至少声明 entry 或 command;command 优先。entry 为相对包根的发行文件:
16
+ process-rpc 至少声明 entry 或 command,command 优先。entry 是相对包根的发行文件:
14
17
 
15
18
  ```json
16
- {
17
- "kind": "process-rpc",
18
- "apiVersion": "1",
19
- "language": "python",
20
- "entry": "runner.py"
21
- }
19
+ { "kind": "process-rpc", "apiVersion": "1", "language": "python", "entry": "runner.py" }
22
20
  ```
23
21
 
24
22
  | language | 默认 argv |
25
23
  |---|---|
26
- | node | 当前 Node 可执行文件、package:entry |
27
- | python | Windows python / 其他平台 python3、-u、package:entry |
28
- | java | java、-jar、package:entry |
29
- | go / rust / custom | package:entry |
24
+ | node | 当前 Node 可执行文件、`package:entry` |
25
+ | python | Windows `python` / 其他 `python3`、`-u`、`package:entry` |
26
+ | java | `java`、`-jar`、`package:entry` |
27
+ | go / rust / custom | `package:entry` |
30
28
 
31
- 需要 JVM 参数时显式覆盖,例如:
29
+ 需要 JVM 参数时显式覆盖:
32
30
 
33
31
  ```json
34
- {
35
- "kind": "process-rpc",
36
- "apiVersion": "1",
37
- "language": "java",
38
- "command": ["java", "-Xmx256m", "-jar", "package:bin/runner.jar"]
39
- }
32
+ { "kind": "process-rpc", "apiVersion": "1", "language": "java", "command": ["java", "-Xmx256m", "-jar", "package:bin/runner.jar"] }
40
33
  ```
41
34
 
42
- command 使用逐参数 argv,shell:false;首参数为已有 PATH 工具名、绝对路径或 package: 包内引用。包内文件在参数中使用完整 package:relative/path,不支持带目录的相对可执行命令、shell 拼接、环境变量展开或重定向。cwd 是宿主创建的临时目录,运行环境经过裁剪,不承诺继承开发者所有环境变量。
35
+ command 是逐参数 argv,`shell:false`;首参数为 PATH 工具名、绝对路径或 `package:` 引用。
36
+ 包内文件用完整 `package:relative/path`,不支持带目录的相对可执行命令、shell 拼接、
37
+ 变量展开或重定向。cwd 是宿主创建的临时目录,环境经过裁剪,不承诺继承开发者的变量。
43
38
 
44
- 外部解释器启用前检查版本;package: 首参数仅查文件,不执行包内程序探测版本,兼容性由发行者验证。原生程序准确声明 platforms/architectures;命令或依赖缺失时报告错误,不自动安装。
39
+ 外部解释器启用前检查版本;`package:` 首参数只查文件、不执行探测,兼容性由发行者验证。
40
+ 原生程序要准确声明 platforms/architectures;命令或依赖缺失时报错,不自动安装。
45
41
 
46
- ## 3. 帧格式
42
+ ## 帧格式
47
43
 
48
- UTF-8、每行一个完整 JSON 对象,行尾换行并及时 flush;stdout 仅输出协议,日志写 stderr。协议标识固定为 evolcore.ability-runtime/1,id 必须为字符串。宿主内部 RPC 使用下述信封,与 AUN 的网络 JSON-RPC 协议分别处理。
44
+ UTF-8,每行一个完整 JSON 对象,行尾换行并及时 flush;stdout 只输出协议,日志写 stderr。
45
+ 协议标识固定 `evolcore.ability-runtime/1`,id 必须为字符串。
46
+ 这是宿主内部 RPC,与 AUN 的网络 JSON-RPC 分开处理。
49
47
 
50
48
  ```json
51
49
  {"protocol":"evolcore.ability-runtime/1","id":"h:1","method":"health","params":{}}
52
- ```
53
-
54
- 响应沿用请求 id,包含 result 或 error:
55
-
56
- ```json
57
50
  {"protocol":"evolcore.ability-runtime/1","id":"h:1","result":{"ready":true}}
58
- ```
59
-
60
- ```json
61
51
  {"protocol":"evolcore.ability-runtime/1","id":"h:2","error":{"code":"PLUGIN_FAILED","message":"Plugin handler failed"}}
62
52
  ```
63
53
 
64
- 宿主目前将 Runner error 归一为 PLUGIN_FAILED,不保证任意自定义错误码透传到 Caller。业务状态若需作为正常结果表达,须明确写入 result_schema 并让调用方能判断成功/失败,不以成功形状隐瞒执行失败。异常日志不包含秘密或不必要的个人数据。
54
+ 宿主目前把 Runner error 归一为 `PLUGIN_FAILED`,不保证自定义错误码透传到 Caller。
55
+ 业务状态要作为正常结果表达时,须写进 `result_schema` 让调用方能判断成功/失败,
56
+ 不用成功形状隐瞒执行失败。异常日志不含秘密或不必要个人数据。
65
57
 
66
- ## 4. 生命周期与 invoke
58
+ ## 生命周期
67
59
 
68
- | 方法 | 宿主请求内容 | Runner 要求 |
60
+ | 方法 | 宿主请求 | Runner 要求 |
69
61
  |---|---|---|
70
- | initialize | config、handlers;可有 migration;旧 Node adapter 另有 entry | 加载配置、核对完整 handler 集合,完成初始化后返回 ready:true 和 handlers |
62
+ | initialize | config、handlers;可有 migration;旧 Node adapter 另有 entry | 加载配置、核对完整 handler 集合,返回 `ready:true` 和 handlers |
71
63
  | health | 空对象 | 返回真实 ready 状态,不执行业务副作用 |
72
- | invoke | invocationId、handler、params、operationId、idempotencyKey、caller | 分发 handler,返回满足 result_schema 的 JSON 结果 |
73
- | cancel | invocationId | 尽力取消;准确返回 cancelled,不虚构已取消 |
74
- | shutdown | 空对象 | 停止接收业务、释放资源并返回 stopped:true |
64
+ | invoke | invocationId、handler、params、operationId、idempotencyKey、caller | 分发 handler,返回满足 `result_schema` 的 JSON |
65
+ | cancel | invocationId | 尽力取消;准确返回 cancelled,不虚构 |
66
+ | shutdown | 空对象 | 停止接收业务、释放资源,返回 `stopped:true` |
75
67
 
76
- initialize 的 handlers 必须与 Manifest 注册集合一致。模板只实现 getReadiness;新增/移除能力后同步修改 Runner。未实现 migration 时明确失败;Node 可通过 migrateData 返回迁移 KV,其他语言需自行实现 migration/migratedData 协议后才能承诺迁移支持。
68
+ initialize 的 handlers 必须与 Manifest 注册集合一致。模板只实现 getReadiness;
69
+ 增删能力后同步改 Runner。未实现 migration 时明确失败;
70
+ Node 可用 `migrateData` 返回迁移 KV,其他语言需自行实现 migration/migratedData 才能承诺迁移。
77
71
 
78
- invoke.caller 来自宿主,含 kind(aun/local)和 aid。不要从业务 params 中取一个 AID 充当认证身份。operationId 标识业务操作,invocationId 关联当前执行,idempotencyKey 用于下游去重;帧 id 只负责 RPC 请求响应匹配。
72
+ `invoke.caller` 来自宿主,含 kind(`aun`/`local`)和 aid。不从业务 params 里取 AID 当认证身份。
73
+ `operationId` 标识业务操作,`invocationId` 关联当前执行,`idempotencyKey` 用于下游去重,
74
+ 帧 id 只负责 RPC 请求响应匹配。
79
75
 
80
- 宿主有握手、健康检查、执行时限、并发及输出限额。实现并发 Runner 时自行关联异步响应,不按到达顺序猜测请求;同步模板的 cancel 通常返回 cancelled:false。进程可能在未收到 shutdown 时被结束,不能把关键数据只保存在内存或退出钩子中。未知执行结果由宿主保留,禁止自动新建操作重放副作用。
76
+ 宿主有握手、健康检查、执行时限、并发和输出限额。实现并发 Runner 时自行关联异步响应,
77
+ 不按到达顺序猜请求;同步模板的 cancel 通常返回 `cancelled:false`。
78
+ 进程可能在没收到 shutdown 时被结束,不能把关键数据只放内存或退出钩子。
79
+ 未知执行结果由宿主保留,禁止自动新建操作重放副作用。
81
80
 
82
- ## 5. 资源 Broker
81
+ ## 资源 Broker
83
82
 
84
- 业务调用中需要宿主资源时,Runner 发反向请求,使用独立且不冲突的 id,并等待对应响应。以下是请求形状示例,其中 invocationId 必须取自当前真实 invoke:
83
+ 业务调用中需要宿主资源时,Runner 发反向请求,用独立不冲突的 id 并等待响应。
84
+ `invocationId` 必须取自当前真实 invoke:
85
85
 
86
86
  ```json
87
87
  {
88
88
  "protocol": "evolcore.ability-runtime/1",
89
89
  "id": "r:1",
90
90
  "method": "broker.call",
91
- "params": {
92
- "invocationId": "current-invocation-id",
93
- "method": "storage.get",
94
- "args": {"key": "example"}
95
- }
91
+ "params": { "invocationId": "current-invocation-id", "method": "storage.get", "args": {"key": "example"} }
96
92
  }
97
93
  ```
98
94
 
99
95
  | Broker 方法 | args | Node ctx 入口 |
100
96
  |---|---|---|
101
- | host.status | 空对象 | ctx.host.status() |
102
- | storage.get / set / delete | key;set 另有 value | ctx.storage.get/set/delete |
103
- | workspace.read / list | file,相对授权 root | ctx.workspace.read/list |
104
- | workspace.write | file、text | ctx.workspace.write |
105
- | http.request | url;可有 method、contentType、body、secretSlot | ctx.http.request |
106
-
107
- Node adapter 已封装反向请求;其他语言自行处理 Broker 响应,并为等待设定合理超时。资源请求仅在有效 invocation 内使用,不在 initialize/health 后台伪造调用上下文。
108
-
109
- 宿主检查实例、执行租约、当前 Owner、Manifest 声明、Grant 范围及有效期。storage 需要有效 storage Grant;workspace/HTTP 同时受 Manifest 和资源 Grant 约束。workspace 当前是文本读写/列表接口,不能当成任意二进制文件、目录创建或流接口。HTTP 仅支持已授权 HTTPS origin,secretSlot 由 Broker 代加授权头,Runner 不接收秘密原文。细节与限制以随包 CLI 手册及实际实现为准。
110
-
111
- 插件不直接建立 AUN、访问 daemon IPC 或读取宿主凭据。独立进程与 Broker 不构成 OS 沙箱,当前只运行经过实际批准的可信插件。Windows generic process-rpc 仍采用 direct spawn,Node 使用已有 Job Object;Unix 使用进程组回收,不宣称通用进程树隔离已经完成。
97
+ | host.status | 空对象 | `ctx.host.status()` |
98
+ | storage.get / set / delete | key;set 另有 value | `ctx.storage.*` |
99
+ | workspace.read / list | file,相对授权 root | `ctx.workspace.read/list` |
100
+ | workspace.write | file、text | `ctx.workspace.write` |
101
+ | http.request | url;可有 method、contentType、body、secretSlot | `ctx.http.request` |
102
+
103
+ Node adapter 已封装反向请求;其他语言自行处理响应并为等待设合理超时。
104
+ 资源请求只在有效 invocation 内使用,不在 initialize/health 后台伪造调用上下文。
105
+
106
+ 宿主检查实例、执行租约、当前 Owner、Manifest 声明、Grant 范围和有效期。
107
+ storage 需要有效 storage Grant;workspace/HTTP 同时受 Manifest 和资源 Grant 约束。
108
+ workspace 当前是文本读写/列表接口,不是任意二进制、目录创建或流接口。
109
+ HTTP 仅支持已授权 HTTPS origin,`secretSlot` 由 Broker 代加授权头,Runner 不接收秘密原文。
110
+
111
+ 插件不直接建 AUN、不访问 daemon IPC、不读宿主凭据。独立进程和 Broker 不构成 OS 沙箱,
112
+ 当前只运行经过实际批准的可信插件。Windows generic process-rpc 仍是 direct spawn,
113
+ Node 用已有 Job Object;Unix 用进程组回收,不宣称通用进程树隔离已完成。