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
@@ -0,0 +1,333 @@
1
+ # ability 技能结构说明
2
+
3
+ 这份文档说明 `kits/skills/ability/` 里每个文件的作用,以及在什么场景下会加载到哪一份。
4
+ 它是给维护者看的,不参与技能运行时。
5
+
6
+ ---
7
+
8
+ ## 一、整体结构
9
+
10
+ ```
11
+ kits/skills/ability/
12
+ ├── SKILL.md ← 技能入口,唯一被 ec skill load 输出的文件
13
+ ├── STRUCTURE.md ← 本文,维护者文档,不参与运行时
14
+ └── references/
15
+ ├── cli.md ← 命令语法
16
+ ├── development.md ← 开发插件
17
+ ├── management.md ← 安装/授权/发布插件
18
+ └── runtime-protocol.md ← 写 Runner 时的 RPC 协议
19
+ ```
20
+
21
+ **5 个运行时文件**,约 53 KB。`SKILL.md` 约 15.7 KB,其余四份按需加载。
22
+
23
+ **关键机制**:`ec skill load ability` 只输出 `SKILL.md` 正文,并在末尾附带技能目录的绝对路径。
24
+ `references/` 下的文件**不会自动进入上下文**——agent 要根据 `SKILL.md` 里的链接,
25
+ 用文件工具主动 Read。
26
+
27
+ **核心设计**:调用别人的能力是这个技能的**主职**,占 `SKILL.md` 的 3/4 篇幅,直接可读、
28
+ 不跳转。开发和管理插件是副线,走 `references/` 按需加载。
29
+
30
+ ---
31
+
32
+ ## 二、每个文件的作用
33
+
34
+ ### `SKILL.md` — 入口,也是核心内容
35
+
36
+ **大小**:15.7 KB | **加载时机**:技能被触发时
37
+
38
+ 分三大部分:
39
+
40
+ | 部分 | 小节 | 内容 |
41
+ |---|---|---|
42
+ | **一、调用别人的能力** | 谁的能力 | 私聊/群聊下"我"指谁的 AID |
43
+ | | 命令 | 七行命令签名 + 六行分支选择表 |
44
+ | | 三层发现 | L1 索引 / L2 discover / L3 契约,字段与校验 |
45
+ | | 输出与分页 | 各命令返回什么、怎么翻页、缓存多久 |
46
+ | | 参数与设备 | `params` 按 Schema 构造、设备选择、`--dry-run`/`--plan` |
47
+ | | 原始 payload | 手工发送的 JSON 形状、时限估算(仅工具不支持时) |
48
+ | | 请求关联与 ACK | `--return` 语义、六个 ID 的分工、状态表 |
49
+ | | 授权 | 为什么不受本机权限约束、`call_permission` 怎么读 |
50
+ | | 结果 | 怎么判断成功、错误码处理、只查不重发 |
51
+ | | 重试边界 | 各类错误能否重试 |
52
+ | **二、开发与管理本机插件** | — | 四行路由表 + 命令速查,指向 references |
53
+ | **三、不能越过的边界** | — | 五条会造成安全事故的规则 |
54
+
55
+ frontmatter 的 `description` 进 `.index-builtin.md`,每个会话都注入,
56
+ 所以只写"什么时候加载",不写流程。
57
+
58
+ **为什么调用能力放在正文而不是 references**:这是技能被加载的首要原因。
59
+ 用户说"用我的手机拍照"时,如果需要先跳一份文件才能开始,就多了一次工具调用;
60
+ 而且版本迭代时,远程调用的规则变动最频繁,放在入口能保证 agent 一定看到最新版。
61
+
62
+ ---
63
+
64
+ ### `references/cli.md` — 命令语法
65
+
66
+ **大小**:11.8 KB | **加载时机**:需要确切参数、JSON 字段、退出码时
67
+
68
+ | 小节 | 内容 |
69
+ |---|---|
70
+ | 身份与命令面 | `capabilities`/`schema`/`context`/`targets`,`--self` 与 `--aid` 的区别 |
71
+ | 实例管理 | 22 条管理命令 + 每个操作的 JSON 业务字段表 |
72
+ | 等待与诊断 | `job`/`status`/`doctor` 的输出含义、`--wait` 范围 |
73
+ | 本地开发与打包 | `dev` 系列、语言矩阵、项目结构、构建行为 |
74
+
75
+ **它和 `management.md`/`development.md` 的关系**:那两份讲流程,这份讲语法。
76
+ 同一批命令在两处出现,但用途不同,不算重复。
77
+ 远端命令的语法在 `SKILL.md` 里,不在这份。
78
+
79
+ ---
80
+
81
+ ### `references/development.md` — 开发插件
82
+
83
+ **大小**:9.1 KB | **加载时机**:要写新插件、改现有插件、打包
84
+
85
+ 六步流程 + 一份检查表:
86
+
87
+ 1. 定需求与验收条件
88
+ 2. 选语言
89
+ 3. 生成项目(`dev init`)
90
+ 4. 实现能力与 Runner(`dev add-ability`)
91
+ 5. 构建、校验、打包(`dev build/check/pack`)
92
+ 6. 验证与交接(进入 management)
93
+
94
+ 末节「实现前检查」按能力定义/权限与副作用/实现与验证/交接四组组织。
95
+ 它放在流程末尾,因为那些检查项只在"开始实现前"才有意义。
96
+
97
+ ---
98
+
99
+ ### `references/management.md` — 管理插件
100
+
101
+ **大小**:10.7 KB | **加载时机**:要把已打包的插件装到某个 AID 上,或改已装实例
102
+
103
+ | 节 | 内容 |
104
+ |---|---|
105
+ | 1. 核实目标与现状 | 装到哪个 AID、现在有什么 |
106
+ | 2. 预览、安装、配置、启用 | 从 tgz 到跑起来的完整步骤 |
107
+ | 3. 四类权限 | 管理权限 / 代码批准 / 资源 Grant / Caller Grant |
108
+ | 4. 秘密与资源 | `secrets --stdin`、workspace/HTTP 的资源边界 |
109
+ | 5. 调用验证与发布 | 自测 → publish → 等 `publicationConverged` |
110
+ | 6. 下架、停用、卸载、版本维护 | 六类维护动作对照表 |
111
+ | 7. 失败与恢复 | 超时、revision 冲突、发布不一致 |
112
+
113
+ 第 7 节覆盖的是**管理阶段**的失败;远端调用的失败处理在 `SKILL.md` 的「结果」里。
114
+
115
+ ---
116
+
117
+ ### `references/runtime-protocol.md` — Runner RPC
118
+
119
+ **大小**:6.1 KB | **加载时机**:只有实现自定义 Runner 或资源 Broker 时
120
+
121
+ | 小节 | 内容 |
122
+ |---|---|
123
+ | 运行方式 | node-subprocess vs process-rpc 的区别和选择 |
124
+ | Manifest 入口 | `entry`/`command` 的写法和各语言默认 argv |
125
+ | 帧格式 | 每行一个 JSON 对象、协议标识、错误归一规则 |
126
+ | 生命周期 | initialize/health/invoke/cancel/shutdown |
127
+ | 资源 Broker | 反向请求、五种 Broker 方法、授权检查 |
128
+
129
+ **为什么单独成篇**:受众完全不同。95% 的任务只需要调能力或装插件,
130
+ 不会碰 Runner 内部协议。
131
+
132
+ ---
133
+
134
+ ## 三、加载流程
135
+
136
+ ### 流程 A:调用别人的能力(以手机拍照为例)
137
+
138
+ ```
139
+ 用户:"用我的手机拍个照"
140
+ ↓
141
+ agent 看到 .index-builtin.md 里 ability 的 description 匹配("用我的手机")
142
+ ↓
143
+ ec skill load ability
144
+ ↓ 输出 SKILL.md 全文
145
+ ↓ 「谁的能力」→ 私聊中"我" = peerId (lwj3214.agentid.cn)
146
+ ↓ 「命令」分支表 → path 未知,先 list
147
+ ↓
148
+ ec ability remote list lwj3214.agentid.cn --search camera
149
+ ↓ 拿到 path,但不知道参数
150
+ ↓ 「命令」→ path 已知就用 info --usage
151
+ ↓
152
+ ec ability remote info lwj3214.agentid.cn camera/capture --usage
153
+ ↓ 拿到 params_schema 和设备候选
154
+ ↓ 「参数与设备」→ 按 Schema 构造参数,唯一设备自动选
155
+ ↓
156
+ ec ability remote call lwj3214.agentid.cn camera/capture --params '{...}'
157
+ ↓
158
+ ├─ 成功 → 「结果」→ business_ok + result_validated 都通过才算成功
159
+ │
160
+ └─ 返回 pending / 超时
161
+ ↓ 「结果」→ 保存 request_id,只查原请求,不重发
162
+ ↓
163
+ ec ability remote result <request-id> --wait 30s
164
+ ↓ 仍无结果时看「请求关联与 ACK」的状态表
165
+ ↓ 需要理解 call_id/request_id/operation_id 关系也在这一节
166
+ ```
167
+
168
+ **全程只读 1 份**:`SKILL.md`。不需要打开任何 references。
169
+
170
+ ---
171
+
172
+ ### 流程 B:给这个 agent 加一个能力
173
+
174
+ ```
175
+ 用户:"给这个 agent 加个查天气的能力"
176
+ ↓
177
+ ec skill load ability
178
+ ↓ 第二部分「开发与管理本机插件」→ 开发阶段读 development.md
179
+ ↓
180
+ Read references/development.md
181
+ ↓ 1. 定需求:输入城市,输出温度,无副作用
182
+ ↓ 「实现前检查」→ 逐项确认契约、权限、验证层级
183
+ ↓ 2. 选语言 → Node
184
+ ↓ 3~5. init / add-ability / build / check / pack
185
+ ↓ 6. 用户要求安装 → 转 management.md
186
+ ↓
187
+ Read references/management.md
188
+ ↓ 1. 核实目标:context --self
189
+ ↓ 2. preview → install → enable
190
+ ↓ 5. invoke 自测 → publish → 等 publicationConverged
191
+ ```
192
+
193
+ **读 3 份**:`SKILL.md` + `development.md` + `management.md`。
194
+ 需要确切命令参数时再读 `cli.md`。
195
+
196
+ ---
197
+
198
+ ### 流程 C:只想看看这个 agent 有哪些插件
199
+
200
+ ```
201
+ 用户:"这个 agent 装了哪些能力插件?"
202
+ ↓
203
+ ec skill load ability
204
+ ↓ 第二部分 → 本机实例查询,命令速查里已有
205
+ ↓
206
+ ec ability list --self
207
+ ```
208
+
209
+ **读 1 份**。`SKILL.md` 的命令速查足以作答,不需要 references。
210
+
211
+ ---
212
+
213
+ ### 流程 D:发布能力后,别人调不通
214
+
215
+ ```
216
+ 用户:"我发布的能力,别人调的时候报错"
217
+ ↓
218
+ ec skill load ability
219
+ ↓
220
+ Read references/management.md
221
+ ↓ 7. 失败与恢复 → 先定阶段
222
+ ↓ status / doctor 看发布是否收敛
223
+ ↓ publicationConverged 未 true → 继续看 outbox,不重发 publish
224
+ ↓ 本地就绪但外部索引未更新 → 报告"发布待收敛"
225
+ ↓
226
+ 确认发布正常,问题在 Caller 侧
227
+ ↓ 回到 SKILL.md「结果」→ 按错误码判断
228
+ ```
229
+
230
+ **读 2 份**:`SKILL.md` + `management.md`。
231
+
232
+ ---
233
+
234
+ ### 流程 E:要写一个 Python Runner
235
+
236
+ ```
237
+ 用户:"我要用 Python 写个插件,需要访问 workspace 里的文件"
238
+ ↓
239
+ ec skill load ability
240
+ ↓
241
+ Read references/development.md
242
+ ↓ 2. 选语言 → Python 用 process-rpc
243
+ ↓ 4. 实现能力与 Runner → 指向 runtime-protocol.md
244
+ ↓
245
+ Read references/runtime-protocol.md
246
+ ↓ 「帧格式」→ 每行一个 JSON、协议标识
247
+ ↓ 「生命周期」→ initialize 要返回 handlers
248
+ ↓ 「资源 Broker」→ workspace.read 的反向请求格式
249
+ ```
250
+
251
+ **读 3 份**。这是唯一会读 `runtime-protocol.md` 的场景。
252
+
253
+ ---
254
+
255
+ ## 四、文件之间的依赖关系
256
+
257
+ ```
258
+ SKILL.md(含全部远端调用内容)
259
+ ├─→ cli.md
260
+ ├─→ development.md ──→ runtime-protocol.md
261
+ └─→ management.md ──→ SKILL.md「一、调用别人的能力」(外部验收时回指)
262
+ ```
263
+
264
+ 三个约束:
265
+
266
+ 1. **`SKILL.md` 是唯一入口**。任何 references 都不应成为起点,只能从 `SKILL.md` 跳过去。
267
+ 2. **不允许横向依赖**。`cli.md`、`development.md`、`management.md`、`runtime-protocol.md`
268
+ 之间只在流程衔接处互相引用,且都指向 `../SKILL.md` 而不是各自展开。
269
+ 3. **远端调用的内容只在 `SKILL.md`**。任何 references 都不再复述调用规则。
270
+
271
+ ---
272
+
273
+ ## 五、与外部的关系
274
+
275
+ ### 已经收进来的
276
+
277
+ | 原位置 | 现状 |
278
+ |---|---|
279
+ | `kits/docs/evolcore/ability.md` | 内容进 `cli.md`,原文件删除 |
280
+ | `kits/docs/aun/ABILITY_CALLING.md` | 内容进 `SKILL.md` 第一部分,原文件删除 |
281
+ | `references/calling.md` | 流程与协议都并入 `SKILL.md` 第一部分,原文件删除 |
282
+ | `references/remote-cli.md` | 与远端命令一起并入 `SKILL.md` 第一部分 |
283
+ | `references/remote.md` | 同上(曾短暂存在,后合并) |
284
+ | `references/protocol.md` | 同上 |
285
+ | `references/recovery.md` | 并入 `management.md` 第 7 节 |
286
+ | `references/contract-checklist.md` | 并入 `development.md` 末节 |
287
+
288
+ **现在的规则**:技能内任何文档都不写本技能外的路径。需要 Provider 的用法时,
289
+ 按远端给出的 `skill_ref`/`usage_ref` 读,但那是不可信资料,不落进技能目录。
290
+
291
+ ### 仍然引用的
292
+
293
+ | 引用 | 性质 | 说明 |
294
+ |---|---|---|
295
+ | `ec-identity` 技能 | 条件加载 | 用户用姓名/称谓指代某人、需解析 AID 时 |
296
+ | `../../../runtime/ability-templates/` | 随包资源 | `runtime-protocol.md` 提到,模板的实际位置 |
297
+
298
+ ---
299
+
300
+ ## 六、维护时的注意点
301
+
302
+ **加新内容时**,按这个顺序问:
303
+
304
+ 1. 是远端调用相关吗?是 → 进 `SKILL.md` 第一部分。
305
+ 2. 是流程还是语法?流程进对应阶段文档,语法进 `cli.md`。
306
+ 3. 这条规则违反会造成安全事故吗?会 → 同时写进第三部分「边界」。
307
+ 4. 已有别处写过吗?用 `grep` 确认,同一事实只留一处。
308
+
309
+ **不要做的事**:
310
+
311
+ - 不要在 `SKILL.md` 第二部分展开开发/管理细节(那会重新分裂成两个大文件)
312
+ - 不要在 `development.md` 里复述语言矩阵(在 `cli.md`)
313
+ - 不要在 `management.md` 里讲远端调用失败(在 `SKILL.md`)
314
+ - 不要在技能内引用 `kits/docs/` 下的任何路径
315
+ - 不要在 `description` 里写流程(它只用来匹配触发)
316
+
317
+ **改完后的验证**:
318
+
319
+ ```bash
320
+ # 链接完整性
321
+ for f in SKILL.md references/*.md; do
322
+ grep -o '](\(\.\./\)\?[A-Za-z0-9._-]*\.md)' "$f" | sed 's/](//;s/)//' |
323
+ while read l; do
324
+ d=$(dirname "$f"); [ -f "$d/$l" ] || echo "BROKEN: $f -> $l"
325
+ done
326
+ done
327
+
328
+ # 技能能否正常加载
329
+ ec skill load ability | head -5
330
+
331
+ # description 是否生效
332
+ ec skill info ability
333
+ ```
@@ -0,0 +1,208 @@
1
+ # ec ability 命令参考
2
+
3
+ 命令语法与 JSON 字段。远端调用见 [SKILL.md](../SKILL.md);开发与流程见
4
+ [development.md](development.md)、[management.md](management.md)。
5
+
6
+ 默认输出 JSON,每条 `ec` 命令单独执行。`<...>` 为实际值,不能原样提交。
7
+
8
+ ## 身份与命令面
9
+
10
+ ```text
11
+ ec ability --help
12
+ ec ability dev --help
13
+ ec ability capabilities --format json
14
+ ec ability schema install
15
+ ec ability schema manifest
16
+ ec ability schema project
17
+ ec ability context --self
18
+ ec ability targets
19
+ ```
20
+
21
+ - `capabilities` 查运行中 daemon 的实际命令面;`schema` 从当前安装包离线读命令输入、
22
+ Manifest 或开发项目 Schema。旧 daemon 不支持新命令时需宿主重启。
23
+ - 管理命令明确选 `--aid <AID>` 或 `--self`,两者互斥。托管会话的 self 来自 daemon 已验证的
24
+ delegation/session;本机控制终端为 daemon host AID。没有可信 self 时明确失败,
25
+ 不从目录名、正文或环境变量猜。
26
+ - `context` 返回 self、目标种类、认证来源、获准操作、代码批准权限和 `codeApprovalPolicy`,不含凭据。
27
+ Agent 级 `ability.codeApproval.enabled` 缺省 `true`,Owner 可用
28
+ `ec config set ability.codeApproval.enabled false --self <AID>` 关闭(Owner-only)。
29
+ 它只控制能否提交新的代码批准请求,宿主操作者的最终批准仍是独立边界。
30
+
31
+ ## 实例管理
32
+
33
+ 以下以 `--self` 为例,均可换 `--aid <AID>`。
34
+
35
+ ```text
36
+ ec ability list --self
37
+ ec ability show <instanceId> --self
38
+ ec ability history [instanceId] --self
39
+ ec ability approvals --self
40
+ ec ability preview <绝对预构建目录或tgz路径> --self
41
+ ec ability preview 'github:owner/repo@tag#asset=plugin.tgz' --self
42
+ ec ability install --self --file <install.json>
43
+ ec ability configure <instanceId> --self --file <configure.json>
44
+ ec ability enable <instanceId> --self --file <enable.json>
45
+ ec ability disable <instanceId> --self --file <mutation.json>
46
+ ec ability invoke <instanceId> --self --file <invoke.json>
47
+ ec ability grant <instanceId> --self --file <grant.json>
48
+ ec ability publish <instanceId> --self --file <publish.json>
49
+ ec ability unpublish <instanceId> --self --file <mutation.json>
50
+ ec ability upgrade <instanceId> --self --file <upgrade.json>
51
+ ec ability rollback <instanceId> --self --file <rollback.json>
52
+ ec ability retire <instanceId> --self --file <retire.json>
53
+ ec ability uninstall <instanceId> --self --file <mutation.json>
54
+ ec ability job <jobId> --self
55
+ ec ability job --self --command-id <originalCommandId>
56
+ ec ability invocation <invocationId> --self
57
+ ec ability secrets <instanceId> --self --slot <slot> --revision <N> --command-id <ID> --stdin
58
+ ```
59
+
60
+ 参数文件是 UTF-8 JSON 对象,放授权项目或当前会话 `$TMPDIR`,不用受保护的配置/凭据路径。
61
+ `--format json` 可显式指定,其他格式不支持。
62
+ 写操作带唯一 `commandId`(也可用 `--command-id`),实例修改带当前 `expectedRevision`。
63
+ 安装默认禁用且未发布。
64
+
65
+ | 操作 | JSON 业务字段(均另带 commandId) |
66
+ |---|---|
67
+ | install | `previewId,name,config`;可有 `approveTrustedCode:true` |
68
+ | configure | `expectedRevision,config`,整体替换 |
69
+ | enable | `expectedRevision`;首次代码批准还需 `approveTrustedCode:true` |
70
+ | disable / unpublish / uninstall | `expectedRevision` |
71
+ | publish | `expectedRevision,paths`,整体替换发布选择 |
72
+ | invoke | `expectedRevision,confirmed:true,path,definitionId,params,operationId` |
73
+ | upgrade | `expectedRevision,previewId,approveTrustedCode:true`;按影响另需来源/兼容/降级/外部数据确认 |
74
+ | rollback / retire | `expectedRevision,generation` |
75
+ | grant | `expectedRevision` 加资源授权、`revokeId` 或 `approvalId/decision` |
76
+
77
+ 升级预览复用 `preview ... --file <JSON>`,文件含 `instanceId`。
78
+
79
+ `unpublish` 把本实例发布集合置空,复用 publish 的权限、CAS、commandId 和持久作业,
80
+ 保留本地 runner。部分撤下用 `publish` 提交剩余 paths。下架是否完成要看远端索引,
81
+ 不能只看发布作业提交成功。
82
+
83
+ 秘密只走独立非交互 stdin,不接受 JSON/argv 明文,不回显。有可写外部目录时再带
84
+ `--acknowledge-external-data`。后端不可用即失败,不降级为明文。
85
+
86
+ ## 等待与诊断
87
+
88
+ ```text
89
+ ec ability job <jobId> --self --wait 30s
90
+ ec ability status [instanceId] --self
91
+ ec ability status [instanceId] --self --wait-publication 30s
92
+ ec ability doctor [instanceId] --self
93
+ ```
94
+
95
+ - `status` 显示 desired/runtime/publication 状态、runner 是否存在、包摘要/版本和发布 outbox。
96
+ `publicationConverged:true` 要求 outbox 无 pending 且实例已 published 或确认 unpublished。
97
+ - `doctor` 只读检查,返回稳定 code、严重程度和建议:代码待批准、运行失败、启用未就绪、
98
+ 发布待确认、发布选择与停用不一致、必需秘密/资源缺失等。它不执行能力、不重放作业、
99
+ 不改授权,也不声称验证过真实网络或业务正确性。
100
+ - `--wait` / `--wait-publication` 只轮询原查询,支持整数 `ms/s/m`(无单位按秒),范围 1ms–60s。
101
+ 超时返回最后状态和 `wait.timedOut:true`,退出码 1;不取消后台作业、不重试、不建新 commandId。
102
+ - 查询/提交的退出码 0 只表示受理成功,必须另查 `data.state`。
103
+ 错误为 `{ok:false,status,code,error}`,成功为 `{ok:true,data}`。
104
+
105
+ ## 本地开发与打包
106
+
107
+ 不依赖 daemon。`build` 可调用本机编译器或显式构建 argv,不启动候选插件的业务 Runner;
108
+ 构建工具是可信本地代码,不是 OS 沙箱。长期文件写授权项目,快照暂存只用绝对 `$TMPDIR`。
109
+ 不自动装环境或依赖,不改 PATH。
110
+
111
+ ```text
112
+ ec ability dev init './plugins/self-status' --id '@example/self-status' --name '自身状态' --target agent --template readiness
113
+ ec ability dev doctor --project './plugins/self-status'
114
+ ec ability dev build --project './plugins/self-status'
115
+ ec ability dev check './plugins/self-status/release'
116
+ ec ability dev pack --project './plugins/self-status'
117
+ ec ability dev add-ability 'example/status' --project './plugins/self-status' --handler getExampleStatus --name '示例状态'
118
+ ec ability dev remove-ability 'example/status' --project './plugins/self-status'
119
+ ec ability dev version 0.2.0 --project './plugins/self-status'
120
+ ```
121
+
122
+ `--target` 必选 `agent|host|both`;`--language` 支持 `node|python|java|go|rust|custom`,默认 Node。
123
+ 模板提供 `self/status`:Node 调 `ctx.host.status()`,其他语言报告 Runner readiness,
124
+ 都只返回 ready 布尔值。默认认证、显式确认和 keyed 幂等。
125
+
126
+ | 语言 | 构建 | 启动 | 需预配环境 |
127
+ |---|---|---|---|
128
+ | Node | 组装已有 ESM | 当前 Node + 宿主 adapter | EvolCore 已用的 Node |
129
+ | Python | 复制声明文件 | Windows `python -u`;其他 `python3 -u` | Python ≥3.9 |
130
+ | Java | `javac --release 17` + `jar` | `java -jar entry` | 构建 JDK ≥17,运行 JRE ≥17 |
131
+ | Go | `go build`,禁用自动工具链和依赖下载 | 直接执行本平台二进制 | 构建 Go ≥1.20;运行不查 |
132
+ | Rust | `rustc --edition=2021` | 直接执行本平台二进制 | 构建 Rust ≥1.70 和链接器;运行不查 |
133
+ | custom | 预构建入口或显式 `build.command` | 直接执行 entry 或 command | 开发者声明并预配 |
134
+
135
+ Java/Go/Rust 的 init 已生成可编译的 readiness 源码,不要求用户先做 Runner。
136
+ 内置 adapter 面向小型无第三方依赖项目;复杂项目用 custom 构建 argv 或预构建文件,
137
+ EvolCore 不自动调用 Maven/Gradle/Cargo/npm install。
138
+
139
+ `dev doctor --language java` 单独查语言环境;`--project` 查项目实际构建与运行命令。
140
+ 无 build 的预构建 JAR 只查 JRE,原生程序只查文件;同时给 language 时必须与项目一致。
141
+ 返回 `{ok:true,data}`,`data.available:false` 时 exit 1。它不证明链接器、业务或 AUN 互通可用。
142
+
143
+ 生成的项目:
144
+
145
+ ```text
146
+ ability-project.json 开发配置
147
+ ability-plugin.json 发行 Manifest
148
+ config.schema.json
149
+ definitions/status.json
150
+ usages/status.json
151
+ src/main.mjs 主入口,导入生成的 handlers.mjs
152
+ src/handlers/getReadiness.mjs 默认导出处理函数
153
+ README.md LICENSE
154
+ release/ build 输出
155
+ artifacts/ pack 的 tgz
156
+ .ability-build.json 构建回执
157
+ ```
158
+
159
+ ```json
160
+ {
161
+ "schemaVersion": "evolcore.ability-project/v1",
162
+ "entry": "src/main.mjs",
163
+ "handlers": { "getReadiness": "src/handlers/getReadiness.mjs" },
164
+ "pendingHandlers": [],
165
+ "files": ["README.md", "LICENSE"]
166
+ }
167
+ ```
168
+
169
+ `build` 复制 Manifest、config Schema、引用的定义/用法、入口、明确的 handler 模块和 `files`,
170
+ 生成 `dist/handlers.mjs` 注册表。handler 复制到 `dist/handlers/<handler>.mjs`,
171
+ 默认导出 `(params, ctx)`。额外文件按相同相对路径复制。
172
+
173
+ Java/Go/Rust 把 `build.sources` 复制到临时快照、在独立目录编译,只把 `build.output` 指定的文件
174
+ 放进发行目录;编译附属文件不自动打包。非 Node 的 `handlers` 指向原语言入口,不生成 JS handler。
175
+ `files` 是额外发行文件不是编译输入;参与编译的辅助源码也必须列入 sources。
176
+ 所有构建输入写进回执摘要。Go/Rust 产物锁定当前 OS/CPU;Java 默认兼容 17,
177
+ 用 `javac` 同目录且 ≥17 的 `jar`;Rust 用 `-O`,Windows 加静态 CRT 参数。
178
+ 没有 build 的预构建原生程序不会自动推断 OS/CPU,须准确填 Manifest;
179
+ custom 新模板默认只支持本机 OS/CPU。
180
+
181
+ process-rpc Manifest 可只写 language 和 entry,宿主按语言生成默认 argv。
182
+ 需要虚拟环境或 JVM 参数时显式写 `command`(优先于 entry),例如
183
+ `["C:/tools/python/python.exe","-u","package:runner.py"]`。命令逐参数执行,`shell:false`;
184
+ 包内路径用 `package:`,不写 shell 重定向或变量展开。编译器/运行时缺失或版本不符时清晰失败。
185
+
186
+ 命令首参数支持 PATH 工具名、绝对路径或 `package:` 引用;带目录的相对可执行路径返回
187
+ `RUNTIME_COMMAND_INVALID`。doctor 和启用前检查不对 `package:` 首参数做版本探测,只查文件;
188
+ 包内程序的版本兼容由发行者验证。
189
+
190
+ 不提供 TypeScript 编译或第三方依赖打包;没有自动 npm/pip install、安装钩子或隐式脚本执行;
191
+ 只有显式 `build.kind=command` 才执行开发者声明的 argv。
192
+ 私有/隐藏/凭据名、测试目录和开发配置不进发行清单,但开发者仍须审查实际文件内容。
193
+
194
+ 输出默认 `release/`,可 `--out <目录>`。重复构建只替换回执绑定且未被手改的旧输出,
195
+ 未知内容不覆盖。源码变更后 pack 返回 `BUILD_STALE`,需重新 build。
196
+ 替换失败会尝试恢复旧发行,恢复失败则报告备份位置。
197
+
198
+ `check` 复用生产包校验,不 import 入口,输出文件清单、契约和包摘要。
199
+ `valid:true` 只表示包格式有效,`businessBehaviorVerified:false` 表示未验证业务。
200
+ `pack` 校验上次回执与发行目录,生成固定排序/时间戳/权限的 USTAR+gzip,
201
+ 输出 `artifact`、`artifactDigest`(tgz SHA-256)、`packageDigest`(包树摘要)和清单。
202
+ 同内容重复打包摘要相同;不上传、不 commit/tag/push。本地绝对 tgz 可直接交给 `preview`。
203
+
204
+ `add-ability` 写定义、用法,更新 Manifest/开发配置并加入 `pendingHandlers`;
205
+ Node 另生成抛 NOT_IMPLEMENTED 的 handler,其他语言沿用项目入口自注册。
206
+ `remove-ability` 从开发声明和注册表移除能力,保留源文件,不改已安装实例。
207
+ `version` 只改精确 major.minor.patch,之后需重新 build/pack/preview/upgrade。
208
+ 独立 `dev test` 运行器和新的代码审批队列尚未交付。