evolcore 0.0.42-test.0 → 0.0.43-test.0

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 (187) hide show
  1. package/CHANGELOG.md +31 -2
  2. package/bin/ec-safe-output.js +4 -1
  3. package/dist/ability/application-service.js +882 -0
  4. package/dist/ability/authorization.js +70 -0
  5. package/dist/ability/command-contract.js +105 -0
  6. package/dist/ability/daemon.js +137 -0
  7. package/dist/ability/development.js +450 -0
  8. package/dist/ability/environment.js +75 -0
  9. package/dist/ability/interop-v1.js +547 -0
  10. package/dist/ability/management.js +79 -0
  11. package/dist/ability/package.js +264 -0
  12. package/dist/ability/provider.js +73 -0
  13. package/dist/ability/publication.js +107 -0
  14. package/dist/ability/resources.js +106 -0
  15. package/dist/ability/runtime.js +212 -0
  16. package/dist/ability/secrets.js +47 -0
  17. package/dist/ability/store.js +112 -0
  18. package/dist/ability/toolchain.js +69 -0
  19. package/dist/ability/types.js +14 -0
  20. package/dist/ability/versions.js +32 -0
  21. package/dist/agents/baseagent.js +2 -2
  22. package/dist/agents/claude-runner.js +4 -0
  23. package/dist/agents/codex-runner.js +81 -17
  24. package/dist/agents/ecagent-plugin-lazy.js +41 -0
  25. package/dist/agents/ecagent-runner.js +18 -11
  26. package/dist/aun/ability-device-routing.js +12 -1
  27. package/dist/aun/aid/agentmd.js +2 -2
  28. package/dist/aun/aid/identity.js +45 -0
  29. package/dist/aun/aid/index.js +1 -0
  30. package/dist/aun/aid/managed-operation.js +73 -2
  31. package/dist/channels/aun.js +64 -18
  32. package/dist/channels/builtin-plugins.js +14 -0
  33. package/dist/channels/dingtalk.js +78 -26
  34. package/dist/channels/feishu.js +89 -14
  35. package/dist/channels/qqbot.js +84 -19
  36. package/dist/channels/wechat.js +77 -19
  37. package/dist/channels/wecom.js +67 -22
  38. package/dist/cli/ability-command.js +92 -0
  39. package/dist/cli/aun-commands.js +124 -85
  40. package/dist/cli/daemon-commands.js +37 -85
  41. package/dist/cli/index.js +14 -0
  42. package/dist/cli/init.js +11 -13
  43. package/dist/cli/managed-command-guard.js +6 -0
  44. package/dist/cli/model.js +101 -104
  45. package/dist/cli/provider-command.js +6 -4
  46. package/dist/cli/restart-monitor.js +52 -11
  47. package/dist/cli/upgrade-command.js +102 -0
  48. package/dist/cli/version.js +1 -1
  49. package/dist/config/access-policy.js +4 -2
  50. package/dist/config/builtin-roles.js +1 -0
  51. package/dist/config/config-field-policy.js +4 -0
  52. package/dist/config/config-manager.js +7 -0
  53. package/dist/config/provider-ipc-service.js +10 -0
  54. package/dist/config/providers-config.js +12 -3
  55. package/dist/config/providers-management.js +45 -9
  56. package/dist/config/schema-migration.js +40 -22
  57. package/dist/contracts/ecweb-service-protocol.js +2 -1
  58. package/dist/core/auth/agent-delegation.js +21 -5
  59. package/dist/core/auth/auth-gateway.js +31 -9
  60. package/dist/core/auth/authorization-audit.js +52 -4
  61. package/dist/core/auth/delegation-authorization.js +140 -4
  62. package/dist/core/auth/operation-authorizer.js +114 -13
  63. package/dist/core/auth/operation-catalog.js +118 -4
  64. package/dist/core/baseagent-loader.js +14 -1
  65. package/dist/core/channel-loader.js +47 -9
  66. package/dist/core/channel-runtime.js +1 -1
  67. package/dist/core/command/agent-storage-menu.js +1 -1
  68. package/dist/core/command/cli-intent-parser.js +26 -13
  69. package/dist/core/command/command-handler.js +232 -76
  70. package/dist/core/command/connect-menu.js +10 -4
  71. package/dist/core/command/daemon-diagnostics.js +3 -3
  72. package/dist/core/command/data-root-resolver.js +2 -3
  73. package/dist/core/command/menu-catalog.js +10 -3
  74. package/dist/core/command/menu-handler.js +321 -46
  75. package/dist/core/command/menu-protocol.js +53 -7
  76. package/dist/core/command/pa-workspace-calendar.js +1 -2
  77. package/dist/core/command/pa-workspace-items.js +486 -0
  78. package/dist/core/command/pa-workspace-store.js +10 -1
  79. package/dist/core/command/slash-gate.js +2 -2
  80. package/dist/core/command/slash-handler.js +67 -25
  81. package/dist/core/contact-bind-registry.js +27 -0
  82. package/dist/core/daemon-control.js +3 -3
  83. package/dist/core/daemon-lifecycle.js +2 -1
  84. package/dist/core/event-bus.js +9 -2
  85. package/dist/core/handoff/ipc-registration.js +1 -0
  86. package/dist/core/host-snapshot.js +1 -2
  87. package/dist/core/initialization/service.js +32 -11
  88. package/dist/core/ipc-registration.js +18 -5
  89. package/dist/core/memory/consolidation-context.js +2 -2
  90. package/dist/core/message/aun-request-registry.js +99 -18
  91. package/dist/core/message/im-renderer.js +16 -11
  92. package/dist/core/message/message-admission.js +25 -20
  93. package/dist/core/message/message-bridge.js +21 -47
  94. package/dist/core/message/message-queue.js +3 -0
  95. package/dist/core/message/response-engine.js +7 -5
  96. package/dist/core/model/catalog-service.js +1 -1
  97. package/dist/core/permission/ec-command-parser.js +41 -9
  98. package/dist/core/permission/permission-result.js +1 -0
  99. package/dist/core/permission/protected-paths.js +25 -14
  100. package/dist/core/permission/tool-policy.js +108 -107
  101. package/dist/core/plugin-lifecycle.js +133 -0
  102. package/dist/core/runner-reload-transaction.js +4 -1
  103. package/dist/core/system-session/memory.js +16 -3
  104. package/dist/core/task/task-activity-store.js +50 -0
  105. package/dist/core/task/task-image-resources.js +140 -0
  106. package/dist/core/thread/ipc-operation.js +1 -1
  107. package/dist/core/thread/thread-service.js +0 -1
  108. package/dist/directory/canonical-digest.js +5 -3
  109. package/dist/directory/owner-directory-admission.js +22 -2
  110. package/dist/directory/owner-directory-cache.js +394 -60
  111. package/dist/directory/owner-directory-markdown.js +29 -2
  112. package/dist/directory/owner-directory-scope.js +35 -16
  113. package/dist/ecweb/basic-settings-service.js +4 -1
  114. package/dist/ecweb/pairing.js +41 -0
  115. package/dist/ecweb/providers-service.js +8 -1
  116. package/dist/{utils/ecweb-utils.js → ecweb/runtime/launch.js} +3 -27
  117. package/dist/ecweb/runtime/lifecycle.js +184 -0
  118. package/dist/{utils/ecweb-supervisor.js → ecweb/runtime/supervisor.js} +32 -27
  119. package/dist/index.js +34 -25
  120. package/dist/ipc.js +124 -7
  121. package/dist/response-system/engines/v1/proactive-flow.js +1 -1
  122. package/dist/trigger/authorization.js +2 -2
  123. package/dist/utils/atomic-write.js +24 -0
  124. package/dist/utils/avatar-upload.js +3 -1
  125. package/dist/utils/cross-platform.js +31 -2
  126. package/dist/utils/host-info.js +36 -0
  127. package/dist/utils/instance-registry.js +38 -11
  128. package/dist/utils/logger.js +9 -0
  129. package/dist/utils/{process-tree-stats.js → process-tree.js} +29 -0
  130. package/dist/utils/tool-summary.js +9 -1
  131. package/dist/utils/upgrade-jobs.js +96 -15
  132. package/dist/utils/windows-autostart.js +1 -1
  133. package/ecagent/README.md +19 -0
  134. package/ecagent/dist/harness/agent-harness.js +9 -0
  135. package/ecagent/dist/harness/env/nodejs.js +71 -11
  136. package/ecagent/dist/harness/env/windows-shell.d.ts +7 -0
  137. package/ecagent/dist/harness/env/windows-shell.js +132 -0
  138. package/kits/docs/aun/ABILITY_CALLING.md +38 -9
  139. package/kits/docs/evolcore/INDEX.md +5 -1
  140. package/kits/docs/evolcore/ability.md +181 -0
  141. package/kits/docs/evolcore/aid.md +20 -0
  142. package/kits/docs/evolcore/config.md +10 -6
  143. package/kits/docs/evolcore/menu-protocol.md +40 -1
  144. package/kits/docs/evolcore/provider.md +2 -2
  145. package/kits/docs/evolcore/tool-authorization.md +270 -0
  146. package/kits/runtime/ability-job.ps1 +41 -0
  147. package/kits/runtime/ability-runner.mjs +67 -0
  148. package/kits/runtime/ability-secret.ps1 +59 -0
  149. package/kits/runtime/ability-templates/go/main.go +59 -0
  150. package/kits/runtime/ability-templates/java/Json.java +67 -0
  151. package/kits/runtime/ability-templates/java/Runner.java +42 -0
  152. package/kits/runtime/ability-templates/python/runner.py +48 -0
  153. package/kits/runtime/ability-templates/rust/json.rs +87 -0
  154. package/kits/runtime/ability-templates/rust/runner.rs +35 -0
  155. package/kits/schemas/_meta.json +12 -1
  156. package/kits/schemas/ability-plugin.schema.1.json +107 -0
  157. package/kits/schemas/ability-project.schema.1.json +31 -0
  158. package/kits/schemas/agent-config.schema.16.json +20 -0
  159. package/kits/schemas/agent-config.schema.17.json +20 -0
  160. package/kits/schemas/agent-config.schema.18.json +917 -0
  161. package/kits/skills/.switches.json +4 -0
  162. package/kits/skills/aid-ability/SKILL.md +5 -4
  163. package/kits/skills/ec-ability/SKILL.md +67 -0
  164. package/kits/skills/ec-ability/references/contract-checklist.md +37 -0
  165. package/kits/skills/ec-ability/references/development.md +104 -0
  166. package/kits/skills/ec-ability/references/management.md +117 -0
  167. package/kits/skills/ec-ability/references/recovery.md +27 -0
  168. package/kits/skills/ec-ability/references/runtime-protocol.md +109 -0
  169. package/kits/skills/ec-ability/references/workflows.md +15 -0
  170. package/kits/skills/ec-service-proxy/SKILL.md +12 -0
  171. package/kits/skills/personal-assistant/SKILL.md +240 -6
  172. package/kits/skills/personal-assistant/references/02-bootstrap.md +78 -4
  173. package/kits/skills/personal-assistant/scripts/clean.mjs +397 -0
  174. package/kits/skills/personal-assistant/scripts/init.mjs +113 -25
  175. package/kits/skills/personal-assistant/scripts/lock.mjs +189 -0
  176. package/kits/skills/personal-assistant/scripts/migrate.mjs +35 -10
  177. package/kits/skills/personal-assistant/scripts/verify.mjs +2 -1
  178. package/kits/skills/personal-assistant/templates/persona-section.md +54 -0
  179. package/kits/skills/personal-assistant/triggers/ingest-daily.json +1 -1
  180. package/kits/templates/memory-consolidation/notes.md +1 -1
  181. package/kits/templates/system-fragments/channel.md +2 -1
  182. package/kits/templates/system-fragments/commands.md +1 -0
  183. package/package.json +4 -2
  184. package/dist/core/command/data-root-error.js +0 -10
  185. package/dist/utils/machine-info.js +0 -46
  186. package/dist/utils/process-tree-worker.js +0 -31
  187. package/dist/utils/windows-output.js +0 -36
@@ -42,5 +42,9 @@
42
42
  "ec-service-proxy": {
43
43
  "enabled": true,
44
44
  "locked": false
45
+ },
46
+ "ec-ability": {
47
+ "enabled": true,
48
+ "locked": false
45
49
  }
46
50
  }
@@ -1,10 +1,10 @@
1
1
  ---
2
2
  name: aid-ability
3
3
  description: >-
4
- 发现并调用 AUN AID 发布的数据与操作能力。用户想获取、读取、查询或汇总属于某个主体的数据时
4
+ 发现并调用其他 AUN AID 发布的数据与操作能力。用户想获取、读取、查询或汇总属于某个主体的数据时
5
5
  (无论用“我”、姓名、关系称谓或 AID 指代),先确认主体身份并解析到准确 AID,再检查该 AID 的能力索引
6
6
  是否提供匹配的数据能力;数据类型和来源不设限。即使没有提到“能力”或“调用”也适用。
7
- 用户要求某个 AID 执行操作,或消息中出现 ability、protocol/discover、ability_path、call_id、operation_id 时也使用。
7
+ 用户明确要求发现或调用远端 AID 的能力,或处于远端调用语境并出现 protocol/discover、ability_path、call_id、operation_id 时使用。
8
8
  实际调用前读取能力索引和结构化契约,再按契约发送原始 JSON 并按 request_id 查询结果。
9
9
  如果用户仅询问流程/可行性,或明确要求不要执行,只说明能力发现与调用思路,不实际读取索引或调用能力。
10
10
  不用于普通聊天、文件传输或群管理。
@@ -27,11 +27,12 @@ allowed-tools: Read, Bash
27
27
  - 能力提供的数据类型和来源不设限。若用户泛指“其他能获取的数据”,先查看目标 AID 的能力索引并说明其中相关的数据能力;只调用用户明确要求且契约允许的范围,不把泛化表述扩展成读取无关数据。
28
28
  - 若用户仅询问流程、可能性或明确要求不要实际执行,只解释会检查目标 AID 的能力索引和匹配契约,不读取索引、不调用能力、不获取数据。
29
29
  - 实际调用目标是 Provider 的 AID 和精确的 `ability_path`。
30
+ - 若用户要求给当前 Agent/主机开发、安装、启用、发布、下架或维护自己的插件,改用 `ec-ability`;不要把本地 Provider 管理误判为远端调用。
30
31
  - `device_id`、`slot_id`、`to_device_id`、`target_runtime_ref`、`sender_slot_id` 是 SDK/transport
31
32
  内部字段,不要向用户索取、从自然语言猜测或写入 Ability 调用。具体设备路由遵循能力契约;
32
33
  契约没有说明时不要自行推断。
33
- - 当前 EvolCore 没有 `ec ability list/info/call` 命令。在 Provider 是当前 AUN 私聊对端时,使用
34
- `ec fs cat` 直接读取公开目录;使用 `ec msg --payload` 发送协议消息。
34
+ - `ec ability` 用于管理本地 Provider 插件,不是远端调用接口。发现和调用远端 Provider 时,在 Provider 是当前 AUN 私聊对端的前提下,使用
35
+ `ec fs cat` 读取公开目录,并使用 `ec msg --payload` 发送协议消息。
35
36
  - 每次工具调用仍遵守托管会话的单命令约束;不要把多个 `ec` 命令拼在一次 Shell 调用里。
36
37
 
37
38
  ## 2. 发现能力
@@ -0,0 +1,67 @@
1
+ ---
2
+ name: ec-ability
3
+ description: >-
4
+ 开发和管理当前 Agent 或主机 AID 的能力插件,支持从需求、契约、源码实现到构建打包、安装验证和发布的完整流程。
5
+ 用户要求“给你增加能力”“把脚本或项目做成能力”“开发插件”“插件支持哪些语言、需要哪些文件”,
6
+ 或要求安装、配置、启停、授权、上架下架、升级回滚、诊断本端能力插件时使用。
7
+ 依据需求、源码、发行包或已安装实例选择起点;离线开发可独立进行,进入实例管理时再核实目标 AID 和权限。
8
+ 不用于发现和调用远端 AID 的能力(用 aid-ability)、EC Skill 管理、普通脚本任务或 base agent 自身的插件配置。
9
+ license: MIT
10
+ compatibility: EvolCore CLI; instance management requires a running daemon and target authorization
11
+ ---
12
+
13
+ # EC 能力插件:开发与管理
14
+
15
+ 用一个入口完成 Provider 侧的开发、安装、运行和发布。一个插件包可以提供多项能力;安装实例归属 Agent/主机 AID,公开调用地址为 Provider AID + ability_path。多个 Caller 可以经宿主调用同一 Provider 实例,分别检查授权和记录审计。
16
+
17
+ ## 1. 判断起点与完成范围
18
+
19
+ 先从已有上下文确定用户要做什么、有何现成产物、要求交付到哪个阶段。只询问真正缺失且影响执行的信息。
20
+
21
+ | 用户意图或现成产物 | 从哪里开始 | 按需读取 |
22
+ |---|---|---|
23
+ | 仅讨论设计、语言支持或可行性 | 解释契约、结构与实现选择;遵守用户“不执行”的要求 | [开发指南](references/development.md) |
24
+ | 新需求、脚本、源码项目 | 检查已有项目,定义契约、实现并构建 | [开发指南](references/development.md)、[契约检查表](references/contract-checklist.md) |
25
+ | 手写非 Node Runner 或使用 Broker | 实现进程协议与资源交互 | [运行时协议](references/runtime-protocol.md) |
26
+ | 已有发行目录或 tgz | 核实目标 AID,预览、安装、配置、启用、验证 | [管理指南](references/management.md) |
27
+ | 已有实例;授权、发布下架、升级或故障 | 读取实例和作业状态,执行指定管理阶段 | [管理指南](references/management.md)、[恢复指南](references/recovery.md) |
28
+
29
+ 开发完成后自然衔接同一管理流程。用户要求“开发并安装/发布”且授权覆盖后续操作时,持续推进到该阶段;只要求开发或设计时交付对应产物。具体受保护操作仍以实际权限和必要批准为准。
30
+
31
+ ## 2. 查阅顺序
32
+
33
+ 1. 按当前阶段查阅随包手册 `<包根>/kits/docs/evolcore/ability.md` 的对应章节,参数和字段以实际 `ec ability --help`、`dev --help` 及 `schema` 为准。
34
+ 2. 只加载当前阶段需要的 references;路径从 `ec skill load ec-ability` 返回的 skillDir 拼成绝对路径。不要求一次读完全部引用。
35
+ 3. 离线设计、源码开发、`dev doctor/build/check/pack` 和 `schema` 不依赖 daemon,不先执行 `context --self` 或查询管理权限。
36
+ 4. 进入安装或已有实例管理阶段,再按管理指南查询 daemon 的 `capabilities`、可信 `context`、`targets` 和实例。CLI 较新而 daemon 不支持时报告版本差异。
37
+
38
+ ## 3. 两段连续流程
39
+
40
+ 开发:需求与验收条件 → 语言和已有环境 → 契约与资源声明 → 源码/Runner → doctor → build → check → pack。
41
+
42
+ 管理:目标 AID 与权限 → preview → install → 配置/资源授权/实际代码批准 → enable → 已授权调用验证 → 按需发布与 Caller 授权 → 查询作业和发布收敛。
43
+
44
+ 支持 Node、Python、Java、Go、Rust、custom。Node 使用宿主 adapter,其他语言实现统一 process-rpc;Java/Go/Rust 有真实源码模板与本地编译路径。缺少工具或版本不符时清晰报告,由用户准备环境;不自动安装编译器、运行时或依赖,不修改 PATH。
45
+
46
+ ## 4. 执行约定
47
+
48
+ - 使用 `ec ability` 管理实例、授权、秘密和发布,不手改数据库、索引或运行目录,不自行建立插件 AUN/控制面连接。
49
+ - 当前 Agent/主机由可信 `--self` 解析;显式目标使用 `--aid <AID>`。Owner AID、目录名和显示名不能代替目标身份,选择 AID 不提升权限。
50
+ - 管理权限、代码执行批准、资源 Grant、远端调用 Grant 分别核实。发布不自动授权所有 Caller;不得自行提交代码批准来代替实际宿主操作者决定。
51
+ - 每次 shell 调用仅执行一条完整 `ec` 命令。项目文件写入用户授权位置,临时文件仅用当前会话 `$TMPDIR`;示例占位符须替换为实际结果。
52
+ - 新写操作使用唯一 commandId,实例修改带当前 expectedRevision,安装等按各自 Schema;结果不明先查询原作业/调用,不新建 ID 重放。具体处理见恢复指南。
53
+ - 只读验证或真实业务操作都须符合任务范围;涉及写入、费用或外部联系时确认已有授权覆盖。秘密不写入源代码、Manifest、argv 或普通日志。
54
+ - `dev check` 只证明格式与契约有效;没有独立 `dev test` 命令。源码模板的 readiness 成功不代表新业务已实现。
55
+
56
+ ## 5. 交付标准
57
+
58
+ 按用户要求完成的阶段报告结果;未执行阶段明确标注,不能只说“已完成能力”。
59
+
60
+ | 阶段 | 必须给出的实际证据 |
61
+ |---|---|
62
+ | 开发 | 项目路径、语言、插件 ID/版本、能力路径、环境要求、实现范围 |
63
+ | 构建 | 发行目录/归档路径、包摘要、文件审查、格式检查及业务验证结果 |
64
+ | 管理 | Provider AID、实例 ID、实际安装/运行/授权状态、相关作业结果 |
65
+ | 发布 | 发布路径与 publicationConverged;独立 Caller 验收是否执行 |
66
+
67
+ 构建成功、安装成功、Runner ready、业务结果正确、对外发布收敛、真实 AUN 互通分别核实。作业受理和传输 ACK 都不能作为完整业务成功的证据。
@@ -0,0 +1,37 @@
1
+ # Ability Contract Checklist
2
+
3
+ 开始实现前逐项确定;不适用的项目也要说明原因。
4
+
5
+ ## 能力定义
6
+
7
+ - [ ] 唯一、稳定的 ability path 和清晰的名称、用途及限制。
8
+ - [ ] 参数 schema 定义类型、必填项、边界、默认值及拒绝策略。
9
+ - [ ] 结果 schema 定义成功结果、空结果和稳定错误码;不暴露内部凭据或无关个人数据。
10
+ - [ ] usage 文档描述调用前提、示例、效果、失败和结果解释。
11
+
12
+ ## 权限与副作用
13
+
14
+ - [ ] 明确能力运行于 Agent、host 或两者,以及实际需要的资源。
15
+ - [ ] 遵循最小权限;不把本地 secret 放进 manifest、源代码、参数或日志。
16
+ - [ ] 如会写入、删除、联系第三方或产生费用,明确 `effects`、认证和逐次确认要求。
17
+ - [ ] 定义幂等键及重试行为;不确定前次结果时不得盲目重放非幂等操作。
18
+ - [ ] 只有确实需要外部授权时才设计 grant,并限定主体、资源和操作范围。
19
+
20
+ ## 实现与验证
21
+
22
+ - [ ] 已选择 node/python/java/go/rust/custom,记录构建环境与运行环境、版本和目标 OS/CPU;缺失环境不自动安装。
23
+ - [ ] Manifest runtime 指向真实发行入口,开发 entry/build.sources/files 与实际源码及模块导入一致。
24
+ - [ ] 非 Node Runner 实现所需生命周期和 handler 分发,initialize 返回集合与 Manifest 一致;stdout 仅输出协议。
25
+ - [ ] handler 对无效输入和依赖不可用返回稳定错误,不以成功形状伪装失败。
26
+ - [ ] 处理超时、重复请求和并发边界;不在调用方无法审计的位置写入隐式状态。
27
+ - [ ] `pendingHandlers` 为空,且源码、声明、用法和打包清单一致。
28
+ - [ ] 已检查最终发行文件清单及内容,不包含凭据、测试数据或开发期文件。
29
+ - [ ] 记录实际验证层级:构建/契约检查、授权目标业务执行、外部 AUN Caller 验收。
30
+
31
+ ## 开发到管理的交接
32
+
33
+ - [ ] 交付实际发行目录或 tgz、packageDigest/artifactDigest、插件 ID/版本及能力路径。
34
+ - [ ] 说明配置、秘密槽、Manifest 资源需求及所需资源/Caller Grant;不把声明当成已获授权。
35
+ - [ ] 进入安装或发布时再核实可信目标 AID、当前 revision 和实际批准;只开发时明确尚未安装/发布。
36
+
37
+ `dev check` 通过只能证明包格式有效。没有执行某一层验证时,应明确标记未验证。
@@ -0,0 +1,104 @@
1
+ # 能力插件开发指南
2
+
3
+ ## 1. 确定需求与验收条件
4
+
5
+ 1. 把需求落实为明确输入、可验证输出、失败条件和副作用。区分用户只要设计、源码、发行包,还是希望安装到 AID 并发布。
6
+ 2. 检查用户指定位置是否已有 ability-project.json、Manifest 或可复用实现,优先在原项目完善。
7
+ 3. 确定插件 ID(@publisher/name)、版本、目标类型 agent/host/both、能力 path、handler 和资源需求。开发时选目标类型即可,具体安装 AID 在管理阶段解析。
8
+ 4. 完成 [契约检查表](contract-checklist.md)。从生成的定义/usage 模板修改,遵循当前有限 Schema,不自行增加未支持的协议字段。
9
+
10
+ 纯开发不先查询 daemon 或管理身份。离线命令面可用 `ec ability dev --help`、`ec ability schema manifest`、`ec ability schema project` 查阅。
11
+
12
+ ## 2. 根据现有环境选语言
13
+
14
+ | language | 模板/实现方式 | 构建需求 | 运行需求 |
15
+ |---|---|---|---|
16
+ | node(默认) | ESM handler,宿主 adapter 处理 RPC | 组装已有 JS,不编译 TS | EvolCore 当前 Node;默认范围 ≥22.16、<27 |
17
+ | python | runner.py,实现 process-rpc | 复制声明文件 | Windows python,其他平台 python3;默认 ≥3.9、<4 |
18
+ | java | Runner.java + Json.java | JDK ≥17,javac 和同目录 jar;产物兼容 Java 17 | JRE ≥17,java -jar |
19
+ | go | main.go,标准库 RPC | Go ≥1.20;当前平台/架构,关闭 CGO | 原生二进制,不要求 Go 编译器 |
20
+ | rust | runner.rs + json.rs | Rust ≥1.70 和可用链接器 | 原生二进制,不要求 Rust 编译器 |
21
+ | custom | 自行提供协议入口,模板保持 pending | 预构建文件或显式 build.command | 已配置命令/包内入口及其系统依赖 |
22
+
23
+ 模板版本范围是声明,按 dev doctor 和实际目标环境验证。环境缺失或版本不符时报告具体项,由用户准备;不自动安装工具、依赖或修改 PATH。原生程序仍可能需要目标 OS 的系统库。
24
+
25
+ Node/Python 适合已有脚本;Java/Go/Rust 可复用其生态和现有实现。内置 builder 面向小型无第三方依赖项目;复杂工程由开发者提供显式构建 argv 或预构建产物。没有隐式 Maven、Gradle、Cargo、npm/pip install 或自动依赖打包。
26
+
27
+ ## 3. 生成并理解项目
28
+
29
+ 以下为可执行的 readiness 项目示例,每行独立执行。业务名称和语言按需求替换;init 只接受空目录。
30
+
31
+ ```text
32
+ ec ability dev init './plugins/readiness' --id '@example/readiness' --name 'Readiness' --target agent --language python
33
+ ec ability dev doctor --project './plugins/readiness'
34
+ ```
35
+
36
+ | 文件 | 用途与开发要求 |
37
+ |---|---|
38
+ | ability-project.json | 语言、源码 entry、handlers、pendingHandlers、显式 build 与额外发行 files |
39
+ | ability-plugin.json | 插件身份/版本、兼容范围、runtime、targets、OS/CPU、权限、限额、定义和用法引用 |
40
+ | config.schema.json | 用户配置校验;不要在配置中放秘密原文 |
41
+ | definitions/*.json | path、名称/summary、params_schema、result_schema、effects、认证、确认及幂等声明 |
42
+ | usages/*.json | 对应 path 的参数示例、使用前提、结果解释与限制 |
43
+ | 语言入口及辅助源码 | Node handler 或非 Node Runner;真实实现与声明保持一致 |
44
+ | README.md / LICENSE | 环境、用法、依赖、支持平台、许可和已知限制 |
45
+ | release/ / artifacts/ | 构建后的安装目录及 pack 归档,不作为源码编辑位置 |
46
+ | .ability-build.json | 构建输入/输出摘要回执,由开发工具管理 |
47
+
48
+ Java 项目的 build 配置片段:
49
+
50
+ ```json
51
+ {
52
+ "kind": "java",
53
+ "sources": ["src/Runner.java", "src/Json.java"],
54
+ "output": "bin/runner.jar",
55
+ "mainClass": "Runner"
56
+ }
57
+ ```
58
+
59
+ build.sources 必须包含项目 entry 及所有辅助编译输入;files 只负责额外发行文件。Go 的 .go 文件由内置 builder 一起编译;Rust 以 sources 中第一个 .rs 文件为根入口,辅助模块也要声明并保持目录关系。
60
+
61
+ 已有预构建入口可省略 build,让项目 entry 和 Manifest 的运行引用指向已有文件。Manifest runtime 的 entry 是发行入口,与开发项目的源码 entry 可不同。
62
+
63
+ ## 4. 实现能力与 Runner
64
+
65
+ Node 模板 handler 默认导出 `async function (params, ctx)`;ctx 提供 config、caller、signal、幂等标识以及 host/storage/workspace/http/log 方法,具体映射见 [运行时协议](runtime-protocol.md)。开发工具将 handler 复制到 dist/handlers 并生成注册表,检查其他模块相对 import 是否仍然正确。
66
+
67
+ Python/Java/Go/Rust 模板只实现 getReadiness;要提供业务能力,修改原语言入口的 handler 分发和 initialize 返回集合。使用 Broker 时需自行实现反向请求关联和响应处理。模板没有完整的异步客户端、并发调度或数据迁移实现。
68
+
69
+ ```text
70
+ ec ability dev add-ability 'example/status' --project './plugins/readiness' --handler getExampleStatus --name '示例状态'
71
+ ```
72
+
73
+ add-ability 生成契约、usage 和 pending 标记;Node 另生成 JS handler,非 Node 沿用原语言入口。完成实现、输入输出、effects、usage 和代码审查后,显式移除对应 pendingHandlers 项;不要只清空标记来让构建通过。若需要移除模板 self/status,先添加实际能力再使用 remove-ability,项目至少保留一项能力。
74
+
75
+ 设计重试、超时和幂等:下游副作用使用宿主给出的 idempotencyKey,结果未知时先查原执行。遵守配置和资源授权边界;不让源码依赖开发目录、交互 stdin、隐藏环境变量或本机秘密。进程 cwd 是临时工作区,包资源以入口自身位置解析。
76
+
77
+ 自定义 runtime.command 是 argv,包内文件用 package: 引用。可只填 language + entry 使用默认启动,也可明确选择已有虚拟环境/JVM 参数。协议和具体配置见运行时指南。
78
+
79
+ ## 5. 构建、校验与打包
80
+
81
+ ```text
82
+ ec ability dev build --project './plugins/readiness'
83
+ ec ability dev check './plugins/readiness/release'
84
+ ec ability dev pack --project './plugins/readiness'
85
+ ```
86
+
87
+ build 将声明的编译输入复制到当前会话 TMPDIR 的源码快照,在独立临时目录编译;只有 build.output 指定的单个文件复制进发行目录,编译附属文件不自动打包。Python 的辅助模块和其他运行资源需显式加入 files 并保持相对路径。
88
+
89
+ custom builder 使用 kind=command 的 argv,完整参数 {project} 和 {output} 分别替换为源码快照和编译目标绝对路径;不支持 shell 拼接或子串替换。构建脚本也须加入 sources。编译器及显式构建命令是可信本地代码,没有 OS 沙箱或网络隔离保证;EvolCore 本身不替这些命令准备环境。
90
+
91
+ Java 使用 --release 17 生成 JAR;需要更新 Java 特性时改用显式构建并同步 engines.java。Go 关闭代理、自动工具链下载和 CGO。Rust 优化编译,Windows 增加静态 CRT 参数;目标系统库仍需验证。Go/Rust 构建锁定当前 OS/CPU,省略 build 的预构建原生包需自行正确填写 platforms/architectures,custom 新模板默认仅支持本机 OS/CPU。
92
+
93
+ 审查最终文件清单和内容,确认没有凭据、开发私密文件或未声明产物。源码/版本变化后重新 build,pack 对旧回执返回 BUILD_STALE;手改 release 也会拒绝打包。重复构建只替换原回执绑定且未变更的旧输出,未知目录不覆盖。包和归档沿用 32 MiB 限制。
94
+
95
+ dev check 复用生产包格式/契约校验,不启动 Runner,不验证业务正确性。pack 返回 artifact、artifactDigest、packageDigest,不上传、不安装、不发布。doctor 只检测已有工具,available:false 时 exit 1;能检测版本不代表链接器、原生依赖或业务一定可用。
96
+
97
+ ## 6. 验证与衔接管理
98
+
99
+ 1. 用独立业务测试验证正常/边界输入、数值精度、输出结构、依赖不可用和幂等行为;只执行已授权测试,不使用真实业务写入作默认验收。
100
+ 2. 用户要求安装/使用/发布时,带着实际产物进入 [管理指南](management.md),再解析目标 AID,复用 preview/install/enable/invoke 验证。当前没有独立 dev test 运行器。
101
+ 3. 记录项目路径、语言、插件 ID/版本、paths/handlers、归档路径、摘要、所需配置/资源和验证结果;部署环境未验证的部分明确标注。
102
+ 4. 修改已安装版本时用 `ec ability dev version <major.minor.patch> --project <project>` 后重新 build/pack,交管理流程 preview/upgrade;开发版本命令不改变已安装实例。
103
+
104
+ 源码 readiness、契约检查、实际业务结果、本地管理和外部 AUN Caller 验证分别报告。只完成开发时不得声称能力已经安装或上架。
@@ -0,0 +1,117 @@
1
+ # 能力插件管理指南
2
+
3
+ 开发任务交付安装、使用或发布时,从这里继续;已有包或实例直接进入对应阶段。命令每行独立执行,示例中的路径、ID 和 JSON 文件均替换为实际值。完整参数以随包 ability.md、当前 CLI help/Schema 和 daemon capabilities 为准。
4
+
5
+ ## 1. 核实目标、现有实例与权限
6
+
7
+ 1. 用户说“给你/当前 Agent 增加能力”时,使用当前可信 self;用户明确指定其他 AID 时按授权使用该目标。host 与 agent 是不同目标类型,不能用 Owner AID 或目录名猜测安装位置。
8
+ 2. 执行以下查询,明确认证来源、目标类型和实际获准动作。显式目标用 --aid <AID> 替代 --self,两者互斥。
9
+ 3. 优先复用现有实例和项目。检查 show/status/doctor 及当前版本、paths、配置和 Grant,不重复安装或发布。
10
+
11
+ ```text
12
+ ec ability capabilities --format json
13
+ ec ability context --self
14
+ ec ability targets
15
+ ec ability list --self
16
+ ec ability show <instanceId> --self
17
+ ec ability status <instanceId> --self
18
+ ec ability doctor <instanceId> --self
19
+ ```
20
+
21
+ capabilities 查询运行中的 daemon;schema 从本地安装包读取。版本不一致时说明实际支持范围。拿不到可信身份或目标权限时停止依赖该权限的操作;已授权的离线开发可继续。不改身份、目标、数据库或调用入口来绕过拒绝。
22
+
23
+ ## 2. 预览、安装、配置、启用
24
+
25
+ ```text
26
+ ec ability preview <绝对发行目录或tgz路径> --self
27
+ ec ability schema install
28
+ ec ability install --self --file <install.json>
29
+ ec ability configure <instanceId> --self --file <configure.json>
30
+ ec ability enable <instanceId> --self --file <enable.json>
31
+ ec ability job <jobId> --self --wait 30s
32
+ ```
33
+
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。进程或工具缺失时保留具体错误;不自动准备主机环境。
39
+
40
+ 所有实例写操作带当前 expectedRevision,install 除外;每个新管理操作有唯一 commandId。先运行对应 `ec ability schema <操作>` 准备 UTF-8 JSON 对象,文件位于授权项目或当前 TMPDIR。revision 冲突或请求结果不明按 [恢复指南](recovery.md) 处理,不自动重复写入。
41
+
42
+ ## 3. 分清四类权限
43
+
44
+ | 类别 | 实际作用 | 审查重点 |
45
+ |---|---|---|
46
+ | 管理权限 | 谁能管理指定 AID 的实例和状态 | 可信 context、当前 Owner/宿主权限,不能由 --self 自授 |
47
+ | 可信代码批准 | 是否批准这个包在宿主执行 | 包摘要、来源和实际操作者决定;安装/发布授权不能替代 |
48
+ | 资源 Grant | 实例能使用哪些 KV、workspace、HTTPS 资源 | Manifest 声明、具体绑定、范围及有效期 |
49
+ | remote-call Grant | 哪个 Caller 能调用哪份能力契约 | Caller AID、path、当前 definitionId、期限和额度/审批模式 |
50
+
51
+ ```text
52
+ ec ability schema grant
53
+ ec ability grant <instanceId> --self --file <grant.json>
54
+ ec ability approvals --self
55
+ ```
56
+
57
+ grant JSON 带 commandId/expectedRevision,按用户明确授权的资源或 Caller 范围准备。新增 Grant 的 expiresAt 是未来 Unix 毫秒时间戳,当前要求最长一年;从当前时间计算,不能把过期或示例时间戳照抄为实际授权。
58
+
59
+ | permission | value 的主要字段 |
60
+ |---|---|
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 |
65
+
66
+ 当前 remote-call 模式:persistent 在期限/额度内持续生效;once 仅准入一次新执行;approval 为每个操作进入审批队列。paramsSchema 限定参数范围,maxCalls 限定新执行次数,budgets 只累计声明过的顶层非负整数参数。
67
+
68
+ 新增 remote-call Grant 还须提交 confirmed:true,明确确认 Caller、能力路径与当前不可变契约;不要使用旧 definitionId 或用发布动作替代这项确认。
69
+
70
+ approval 模式当前通过 approvals 查看待决请求,再用 grant 的 approvalId 与 decision=approved/denied 处理。批准本身不执行业务;Caller 须沿用原 operationId、契约和参数,以新的传输请求重试。当前审批记录有效期 10 分钟。Owner 私聊卡片、120 秒同步等待和长窗口迟到批复是后续设计,不写成已支持流程。
71
+
72
+ 撤销指定 Grant 使用实际 revokeId;变更 workspace/http 资源绑定可能改变契约语义和 definitionId,随后重新读取 show/status,检查既有发布与 Caller Grant 是否需重建。Grant 不因复制旧 JSON、切换 AID 或改 display name 自动恢复有效。
73
+
74
+ ## 4. 秘密与资源准备
75
+
76
+ ```text
77
+ ec ability schema secrets
78
+ ec ability secrets <instanceId> --self --slot <slot> --revision <N> --command-id <ID> --stdin
79
+ ```
80
+
81
+ 秘密只经独立非交互 stdin 写入,不放在 JSON 参数文件、argv、源码或日志中,不回显。使用工具支持的非交互输入方式;不要为了传秘密拼接多个 ec 命令。后端不可用时报告并停止该依赖阶段,不使用明文替代。写外部目录涉及的 acknowledgeExternalData / --acknowledge-external-data 按相应命令实际 Schema/help 处理。
82
+
83
+ workspace 与 HTTP Grant 都必须落在 Manifest 声明范围;HTTP secretSlots 仅引用已配置槽,不把秘密交给 Runner。资源授权、业务确认及 Caller 授权分别设置,避免把授权一个能力扩展为授权整个 AID 的其他操作。
84
+
85
+ ## 5. 调用验证与发布
86
+
87
+ ```text
88
+ ec ability schema invoke
89
+ ec ability invoke <instanceId> --self --file <invoke.json>
90
+ ec ability invocation <invocationId> --self
91
+ ec ability publish <instanceId> --self --file <publish.json>
92
+ ec ability status <instanceId> --self --wait-publication 30s
93
+ ```
94
+
95
+ invoke 文件使用当前 path/definitionId、符合契约的 params、confirmed:true、新业务 operationId,以及 commandId/expectedRevision。本地确认调用不创建远端 Caller Grant。选择独立测试数据和用户已授权场景,验证真实结果;不要为“冒烟”擅自执行写入、费用或外部联系。管理 job 完成后还要核实 invocation.state、ok 和实际业务输出;结果披露另受本地 result-read 或远端当前 Caller 授权约束。
96
+
97
+ publish 的 paths 是整体替换集合,从当前实例读取精确路径。先确保 Runner ready,再提交所需 paths,查询原 job,等待 publicationConverged:true。已受理、任务完成、本地 ready、公开索引收敛分别检查。
98
+
99
+ 发布不自动允许所有 Caller。需要时按第 3 节授权用户指定的 Caller;外部发现/调用使用 aid-ability 技能,由获授权的调用方验收,不把本地 invoke 当成真实 AUN 互通证据。
100
+
101
+ ## 6. 下架、停用、卸载与版本维护
102
+
103
+ | 需求 | 动作 | 完成后检查 |
104
+ |---|---|---|
105
+ | 全部下架 | unpublish | 发布收敛为已确认 unpublished;本地实例仍在 |
106
+ | 部分下架 | publish 提交剩余 paths | 核对剩余发布集合及收敛 |
107
+ | 停止运行 | 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 和结果;结束时按主技能的交付表报告真实状态。失败、未批准、发布待收敛或未做外部验收时明确标注。
@@ -0,0 +1,27 @@
1
+ # Ability 作业恢复
2
+
3
+ 管理接口返回“已受理”后,先记录 `commandId`、`jobId`、`instanceId` 和涉及的 revision。写操作超时不代表失败,也不代表未执行。
4
+
5
+ ## 作业等待超时
6
+
7
+ 使用原 `jobId` 查询 `ec ability job`,或使用原 `commandId` 定位作业。需要等待时使用 `--wait`,单次不超过 60 秒;
8
+ 发布状态使用 `status --wait-publication`。等待只查询原状态,不取消后台作业、不重放业务、不创建新 ID。
9
+
10
+ ## 失败与拒绝
11
+
12
+ - 先确定阶段:离线开发查 `dev doctor`、构建回执和发行清单;实例阶段查原 job、`show/status/doctor`,不因管理权限不可用而阻止已授权的离线开发。
13
+ - 运行时或编译器缺失、版本不符时保留具体错误,交用户准备环境;不自动安装、不修改 PATH。已编译 Go/Rust 不因没有编译器而要求重新配置开发工具。
14
+ - Runner 初始化失败时核对发行入口、平台/CPU、initialize handler 集合和 stdout 协议;不要把 readiness 模板当成新业务已经实现。
15
+ - 读取结构化 `code`、`error`、作业状态和 `doctor` 结果,区分输入错误、权限拒绝、代码审批、运行失败和发布未收敛。
16
+ - 权限拒绝时停止该权限依赖的阶段;可继续的离线设计或开发工作可以完成。不得换 AID、身份或命令入口绕过。
17
+ - 代码批准待处理时等待实际宿主操作者决定;批准不能由 `permissionMode=bypass` 或 Skill 文本替代。
18
+ - 业务调用超时或状态未知时查询原 invocation/operation 状态。非幂等能力不得自动重试。
19
+
20
+ ## revision 冲突与发布不一致
21
+
22
+ - `expectedRevision` 冲突后重新执行只读 `show`/`status`/`history`,比较当前变化;不要移除 CAS、自动覆盖或复用过期 revision。
23
+ - 发布作业完成但 `publicationConverged` 尚未为 true 时,继续查看原状态/outbox;不要重复提交 publish。
24
+ - 本地 runtime 已就绪但外部索引未更新时,报告“本地就绪,发布待收敛”,不能报告已发布。
25
+ - unpublish 后仍有本地 runner 是预期状态;只有用户明确要求删除实例时才继续 disable/uninstall。
26
+
27
+ 阶段切换与按需文档见 [完整流程导航](workflows.md)。管理作业 completed 后仍须检查业务 invocation 及其结果;unknown 不自动重放。保留已完成产物和确切阻塞阶段,避免把全部任务笼统标为失败或成功。
@@ -0,0 +1,109 @@
1
+ # Runner 与宿主 RPC
2
+
3
+ ## 1. 选择运行方式
4
+
5
+ Node 默认项目使用 node-subprocess:插件入口导出对象,宿主 adapter 完成协议、handler 分发和 Broker 调用。Python、Java、Go、Rust、custom 使用 process-rpc,Runner 自己读写 stdin/stdout 帧。Node 也可选 process-rpc,但需要自行实现同一协议。
6
+
7
+ 优先用 dev init 生成当前安装包模板,再修改业务逻辑。随包模板位于 [ability-templates](../../../runtime/ability-templates/);Node adapter 位于 [ability-runner.mjs](../../../runtime/ability-runner.mjs)。它们是具体行为依据,模板不等于完整 SDK。
8
+
9
+ ## 2. Manifest 入口
10
+
11
+ process-rpc 至少声明 entry 或 command;command 优先。entry 为相对包根的发行文件:
12
+
13
+ ```json
14
+ {
15
+ "kind": "process-rpc",
16
+ "apiVersion": "1",
17
+ "language": "python",
18
+ "entry": "runner.py"
19
+ }
20
+ ```
21
+
22
+ | language | 默认 argv |
23
+ |---|---|
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 |
28
+
29
+ 需要 JVM 参数时显式覆盖,例如:
30
+
31
+ ```json
32
+ {
33
+ "kind": "process-rpc",
34
+ "apiVersion": "1",
35
+ "language": "java",
36
+ "command": ["java", "-Xmx256m", "-jar", "package:bin/runner.jar"]
37
+ }
38
+ ```
39
+
40
+ command 使用逐参数 argv,shell:false;首参数为已有 PATH 工具名、绝对路径或 package: 包内引用。包内文件在参数中使用完整 package:relative/path,不支持带目录的相对可执行命令、shell 拼接、环境变量展开或重定向。cwd 是宿主创建的临时目录,运行环境经过裁剪,不承诺继承开发者所有环境变量。
41
+
42
+ 外部解释器启用前检查版本;package: 首参数仅查文件,不执行包内程序探测版本,兼容性由发行者验证。原生程序准确声明 platforms/architectures;命令或依赖缺失时报告错误,不自动安装。
43
+
44
+ ## 3. 帧格式
45
+
46
+ UTF-8、每行一个完整 JSON 对象,行尾换行并及时 flush;stdout 仅输出协议,日志写 stderr。协议标识固定为 evolcore.ability-runtime/1,id 必须为字符串。宿主内部 RPC 使用下述信封,与 AUN 的网络 JSON-RPC 协议分别处理。
47
+
48
+ ```json
49
+ {"protocol":"evolcore.ability-runtime/1","id":"h:1","method":"health","params":{}}
50
+ ```
51
+
52
+ 响应沿用请求 id,包含 result 或 error:
53
+
54
+ ```json
55
+ {"protocol":"evolcore.ability-runtime/1","id":"h:1","result":{"ready":true}}
56
+ ```
57
+
58
+ ```json
59
+ {"protocol":"evolcore.ability-runtime/1","id":"h:2","error":{"code":"PLUGIN_FAILED","message":"Plugin handler failed"}}
60
+ ```
61
+
62
+ 宿主目前将 Runner error 归一为 PLUGIN_FAILED,不保证任意自定义错误码透传到 Caller。业务状态若需作为正常结果表达,须明确写入 result_schema 并让调用方能判断成功/失败,不以成功形状隐瞒执行失败。异常日志不包含秘密或不必要的个人数据。
63
+
64
+ ## 4. 生命周期与 invoke
65
+
66
+ | 方法 | 宿主请求内容 | Runner 要求 |
67
+ |---|---|---|
68
+ | initialize | config、handlers;可有 migration;旧 Node adapter 另有 entry | 加载配置、核对完整 handler 集合,完成初始化后返回 ready:true 和 handlers |
69
+ | health | 空对象 | 返回真实 ready 状态,不执行业务副作用 |
70
+ | invoke | invocationId、handler、params、operationId、idempotencyKey、caller | 分发 handler,返回满足 result_schema 的 JSON 结果 |
71
+ | cancel | invocationId | 尽力取消;准确返回 cancelled,不虚构已取消 |
72
+ | shutdown | 空对象 | 停止接收业务、释放资源并返回 stopped:true |
73
+
74
+ initialize 的 handlers 必须与 Manifest 注册集合一致。模板只实现 getReadiness;新增/移除能力后同步修改 Runner。未实现 migration 时明确失败;Node 可通过 migrateData 返回迁移 KV,其他语言需自行实现 migration/migratedData 协议后才能承诺迁移支持。
75
+
76
+ invoke.caller 来自宿主,含 kind(aun/local)和 aid。不要从业务 params 中取一个 AID 充当认证身份。operationId 标识业务操作,invocationId 关联当前执行,idempotencyKey 用于下游去重;帧 id 只负责 RPC 请求响应匹配。
77
+
78
+ 宿主有握手、健康检查、执行时限、并发及输出限额。实现并发 Runner 时自行关联异步响应,不按到达顺序猜测请求;同步模板的 cancel 通常返回 cancelled:false。进程可能在未收到 shutdown 时被结束,不能把关键数据只保存在内存或退出钩子中。未知执行结果由宿主保留,禁止自动新建操作重放副作用。
79
+
80
+ ## 5. 资源 Broker
81
+
82
+ 业务调用中需要宿主资源时,Runner 发反向请求,使用独立且不冲突的 id,并等待对应响应。以下是请求形状示例,其中 invocationId 必须取自当前真实 invoke:
83
+
84
+ ```json
85
+ {
86
+ "protocol": "evolcore.ability-runtime/1",
87
+ "id": "r:1",
88
+ "method": "broker.call",
89
+ "params": {
90
+ "invocationId": "current-invocation-id",
91
+ "method": "storage.get",
92
+ "args": {"key": "example"}
93
+ }
94
+ }
95
+ ```
96
+
97
+ | Broker 方法 | args | Node ctx 入口 |
98
+ |---|---|---|
99
+ | host.status | 空对象 | ctx.host.status() |
100
+ | storage.get / set / delete | key;set 另有 value | ctx.storage.get/set/delete |
101
+ | workspace.read / list | file,相对授权 root | ctx.workspace.read/list |
102
+ | workspace.write | file、text | ctx.workspace.write |
103
+ | http.request | url;可有 method、contentType、body、secretSlot | ctx.http.request |
104
+
105
+ Node adapter 已封装反向请求;其他语言自行处理 Broker 响应,并为等待设定合理超时。资源请求仅在有效 invocation 内使用,不在 initialize/health 后台伪造调用上下文。
106
+
107
+ 宿主检查实例、执行租约、当前 Owner、Manifest 声明、Grant 范围及有效期。storage 需要有效 storage Grant;workspace/HTTP 同时受 Manifest 和资源 Grant 约束。workspace 当前是文本读写/列表接口,不能当成任意二进制文件、目录创建或流接口。HTTP 仅支持已授权 HTTPS origin,secretSlot 由 Broker 代加授权头,Runner 不接收秘密原文。细节与限制以随包 CLI 手册及实际实现为准。
108
+
109
+ 插件不直接建立 AUN、访问 daemon IPC 或读取宿主凭据。独立进程与 Broker 不构成 OS 沙箱,当前只运行经过实际批准的可信插件。Windows generic process-rpc 仍采用 direct spawn,Node 使用已有 Job Object;Unix 使用进程组回收,不宣称通用进程树隔离已经完成。
@@ -0,0 +1,15 @@
1
+ # Ability 完整流程导航
2
+
3
+ 本文件保留为原工作流引用入口。开发与管理使用同一套阶段衔接,详细指令按需加载,避免一次加载全部资料。
4
+
5
+ | 当前阶段 | 读取资料 | 完成后去向 |
6
+ |---|---|---|
7
+ | 需求、语言选择、源码、构建与分发包 | [development.md](development.md) | 用户要求安装/使用/发布时进入管理流程 |
8
+ | 能力定义、资源和业务验收条件 | [contract-checklist.md](contract-checklist.md) | 实现与验证 |
9
+ | 自定义进程 Runner、反向 Broker 请求 | [runtime-protocol.md](runtime-protocol.md) | 构建与授权目标验证 |
10
+ | 安装、配置、启停、授权、发布下架、升级回滚 | [management.md](management.md) | 查询实际作业/运行/发布结果 |
11
+ | 超时、错误、权限拒绝、冲突和恢复 | [recovery.md](recovery.md) | 查询原记录后继续被授权阶段 |
12
+
13
+ 离线开发和本地 Schema 不依赖 daemon;进入实例管理阶段才检查可信目标 AID 和权限。开发任务要求完整交付时,在用户授权范围内继续完成后续管理阶段,无需因为跨文档而重新要求用户授权。
14
+
15
+ 字段和参数以随包手册 `<包根>/kits/docs/evolcore/ability.md`、当前 CLI help/Schema 和 daemon capabilities 为准。references 相对路径从技能目录解析。
@@ -12,6 +12,18 @@ license: MIT
12
12
  用 ec proxy 管理当前 daemon 的 services 配置、AUN 代理发布,以及明确标记为 managed 的本地服务。
13
13
  先查询当前状态;写操作必须用查询所得的 configRev 做 CAS。不要直接编辑 daemon.json。
14
14
 
15
+ ## 长期运行服务(Windows 特别注意)
16
+
17
+ > **Windows 用户:不要在 Bash 工具中用 `cmd &` 启动需要持续运行的服务。**例如 `node server.js &`、
18
+ > `npm run start &`,或用 `&` 启动后再继续执行其它命令。Windows 下后台子进程可能继承 Bash 的
19
+ > stdout/stderr 管道,导致工具调用迟迟不结束,直至超时并触发中断;重定向输出也不能可靠规避此问题。
20
+ > 超时中断会终止该命令的受管进程树,因此不要用这种方式启动希望继续存活的服务。
21
+
22
+ 需要长期运行的本地服务时,优先配置为 `runtime.mode=managed`,让 EvolCore daemon 独立启动并管理,
23
+ 再配置健康检查并通过 `ec proxy start/stop/restart` 控制生命周期。不要把 `cmd &` 当作 Service Proxy
24
+ 或脱离终端的替代方式。若服务不适合由 Service Proxy 管理,使用操作系统的服务管理器;不要从 Bash
25
+ 后台化启动。具体配置见下方「配置」和「发布与生命周期」。
26
+
15
27
  ## 查询
16
28
 
17
29
  1. 列出服务和代理目标: