evolcore 0.0.48 → 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 (302) hide show
  1. package/CHANGELOG.md +97 -0
  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 +285 -8
  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 +9 -2
  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 +31 -2
  41. package/dist/aun/msg/upload.js +126 -3
  42. package/dist/build-identity.json +1 -1
  43. package/dist/channels/aun.js +1175 -457
  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/directory.js +6 -1
  54. package/dist/cli/ecmsg-gateway.js +11 -9
  55. package/dist/cli/index.js +30 -5
  56. package/dist/cli/init.js +39 -63
  57. package/dist/cli/managed-command-guard.js +3 -0
  58. package/dist/cli/menu-client.js +32 -7
  59. package/dist/cli/model.js +20 -5
  60. package/dist/cli/pay-command.js +30 -0
  61. package/dist/cli/provider-command.js +6 -2
  62. package/dist/cli/quota.js +89 -0
  63. package/dist/cli/restart-monitor.js +2 -2
  64. package/dist/cli/role.js +1 -0
  65. package/dist/cli/services-command.js +12 -9
  66. package/dist/cli/team-workspace-command.js +56 -2
  67. package/dist/cli/thread-command.js +78 -12
  68. package/dist/config/access-policy.js +16 -3
  69. package/dist/config/config-field-policy.js +88 -9
  70. package/dist/config/config-manager.js +97 -47
  71. package/dist/config/config-operation-service.js +22 -1
  72. package/dist/config/gateway-config.js +9 -8
  73. package/dist/config/owner-config.js +0 -16
  74. package/dist/config/peer-role-resolver.js +1 -7
  75. package/dist/config/providers-config.js +107 -20
  76. package/dist/config/providers-management.js +45 -21
  77. package/dist/config/resolved-config-op.js +4 -44
  78. package/dist/config/schema-migration.js +78 -5
  79. package/dist/config/schema-registry.js +52 -7
  80. package/dist/config-store.js +1309 -17
  81. package/dist/core/agent-application-service.js +220 -1
  82. package/dist/core/agent-ipc-registration.js +19 -2
  83. package/dist/core/agent-reload-coordinator.js +5 -0
  84. package/dist/core/agent-runtime.js +198 -54
  85. package/dist/core/auth/agent-delegation.js +14 -0
  86. package/dist/core/auth/delegation-authorization.js +33 -26
  87. package/dist/core/auth/operation-authorizer.js +16 -1
  88. package/dist/core/auth/operation-catalog.js +59 -7
  89. package/dist/core/baseagent-loader.js +30 -3
  90. package/dist/core/capability/capability-manager.js +16 -7
  91. package/dist/core/channel-runtime.js +4 -2
  92. package/dist/core/command/agent-control.js +20 -2
  93. package/dist/core/command/agent-template-menu.js +4 -3
  94. package/dist/core/command/cli-intent-parser.js +28 -0
  95. package/dist/core/command/command-handler.js +45 -2
  96. package/dist/core/command/menu-catalog.js +20 -4
  97. package/dist/core/command/menu-file-path.js +70 -0
  98. package/dist/core/command/menu-handler.js +97 -73
  99. package/dist/core/command/menu-protocol.js +29 -0
  100. package/dist/core/command/menu-query-batch.js +2 -2
  101. package/dist/core/command/private-mention-menu.js +71 -0
  102. package/dist/core/command/remote-shell.js +565 -0
  103. package/dist/core/command/slash-handler.js +17 -26
  104. package/dist/core/command/team-workspace-bootstrap.js +2 -1
  105. package/dist/core/command/topic-slash.js +7 -1
  106. package/dist/core/daemon-bootstrap.js +0 -4
  107. package/dist/core/daemon-control.js +58 -1
  108. package/dist/core/daemon-lifecycle.js +29 -7
  109. package/dist/core/evolagent-registry.js +18 -9
  110. package/dist/core/handoff/runtime.js +1 -1
  111. package/dist/core/host-snapshot.js +8 -3
  112. package/dist/core/initialization/service.js +3 -0
  113. package/dist/core/interaction-router.js +130 -0
  114. package/dist/core/ipc-registration.js +5 -0
  115. package/dist/core/memory/consolidation-context.js +2 -1
  116. package/dist/core/memory/consolidation.js +35 -64
  117. package/dist/core/message/aun-ipc-sender.js +213 -74
  118. package/dist/core/message/aun-request-registry.js +31 -0
  119. package/dist/core/message/contact-admission.js +91 -6
  120. package/dist/core/message/contact-pending-inbound.js +113 -0
  121. package/dist/core/message/contact-thread-approval.js +212 -0
  122. package/dist/core/message/im-renderer.js +40 -1
  123. package/dist/core/message/message-admission.js +5 -39
  124. package/dist/core/message/message-bridge.js +197 -45
  125. package/dist/core/message/message-log.js +32 -0
  126. package/dist/core/message/message-queue.js +102 -18
  127. package/dist/core/message/peer-mode.js +15 -4
  128. package/dist/core/message/response-engine.js +174 -26
  129. package/dist/core/message/send-options.js +37 -3
  130. package/dist/core/message/send-routing.js +11 -7
  131. package/dist/core/model/config-scope.js +6 -14
  132. package/dist/core/model/model-catalog.js +5 -5
  133. package/dist/core/model/model-diagnostics.js +19 -0
  134. package/dist/core/model/model-fallback.js +13 -2
  135. package/dist/core/ownership/owner-resolver.js +12 -86
  136. package/dist/core/pack-auth.js +7 -0
  137. package/dist/core/pack-install.js +1 -1
  138. package/dist/core/permission/ec-command-parser.js +288 -77
  139. package/dist/core/permission/protected-paths.js +64 -9
  140. package/dist/core/permission/services-path-acl.js +458 -0
  141. package/dist/core/permission/tool-policy.js +26 -10
  142. package/dist/core/relation/peer-identity.js +13 -0
  143. package/dist/core/session/adapters/claude-session-file-adapter.js +6 -2
  144. package/dist/core/session/adapters/codex-session-file-adapter.js +4 -0
  145. package/dist/core/session/session-manager.js +47 -10
  146. package/dist/core/session/session-mapper.js +16 -0
  147. package/dist/core/skill/index-generator.js +2 -3
  148. package/dist/core/skill/switch-resolver.js +3 -0
  149. package/dist/core/task/task-recovery-service.js +1 -0
  150. package/dist/core/thread/command-parser.js +4 -1
  151. package/dist/core/thread/ipc-operation.js +4 -2
  152. package/dist/core/thread/thread-operation.js +25 -10
  153. package/dist/core/thread/thread-service.js +294 -55
  154. package/dist/core/thread/topic-id.js +67 -2
  155. package/dist/core/thread/types.js +15 -1
  156. package/dist/directory/owner-directory-admission.js +11 -8
  157. package/dist/directory/owner-directory-cache.js +19 -0
  158. package/dist/directory/owner-directory-markdown.js +1 -1
  159. package/dist/directory/owner-directory-policy.js +5 -30
  160. package/dist/directory/owner-directory-request-operation.js +5 -2
  161. package/dist/eck/kit-renderer.js +3 -2
  162. package/dist/eck/message-renderer.js +28 -5
  163. package/dist/ecweb/basic-settings-service.js +5 -9
  164. package/dist/ecweb/providers-service.js +4 -2
  165. package/dist/ecweb/runtime/supervisor.js +36 -8
  166. package/dist/event-center/center-config.js +9 -5
  167. package/dist/event-center/dispatcher.js +10 -1
  168. package/dist/event-center/ipc-operation.js +19 -0
  169. package/dist/event-center/registry.js +20 -5
  170. package/dist/event-center/runtime.js +10 -7
  171. package/dist/index.js +120 -41
  172. package/dist/ipc.js +83 -3
  173. package/dist/outputs/authorization.js +16 -0
  174. package/dist/outputs/cards.js +336 -0
  175. package/dist/outputs/events.js +3 -2
  176. package/dist/outputs/protocol.js +1 -0
  177. package/dist/outputs/service.js +2 -15
  178. package/dist/paths.js +48 -1
  179. package/dist/pay/command.js +38 -0
  180. package/dist/pay/protocol.js +136 -0
  181. package/dist/pay/runtime.js +188 -0
  182. package/dist/pay/service.js +384 -0
  183. package/dist/pay/store.js +81 -0
  184. package/dist/response-system/engines/v1/proactive-flow.js +29 -2
  185. package/dist/services/dispatcher.js +23 -5
  186. package/dist/services/host/main.js +388 -0
  187. package/dist/services/host/protocol.js +118 -0
  188. package/dist/services/host/resident.js +310 -0
  189. package/dist/services/host-client.js +386 -0
  190. package/dist/services/host-deploy.js +180 -0
  191. package/dist/services/host-launch.js +117 -0
  192. package/dist/services/host-recycle.js +203 -0
  193. package/dist/services/host-runtime.js +802 -0
  194. package/dist/services/idempotency.js +44 -86
  195. package/dist/services/index-generator.js +4 -3
  196. package/dist/services/index.js +204 -22
  197. package/dist/services/ipc-operation.js +288 -44
  198. package/dist/services/pack-manager.js +1 -0
  199. package/dist/services/script-runner.js +515 -83
  200. package/dist/services/service-payload.js +13 -7
  201. package/dist/services/validation.js +109 -4
  202. package/dist/stats/budget.js +1 -1
  203. package/dist/stats/model-resolver.js +2 -2
  204. package/dist/stats/quota-query.js +95 -0
  205. package/dist/trigger/application-service.js +6 -4
  206. package/dist/trigger/local-files.js +19 -9
  207. package/dist/trigger/scheduler.js +22 -12
  208. package/dist/trigger/script-sandbox.js +51 -8
  209. package/dist/utils/aid-bind.js +3 -0
  210. package/dist/utils/atomic-write.js +22 -8
  211. package/dist/utils/evolcore-version.js +2 -2
  212. package/dist/utils/host-info.js +173 -1
  213. package/dist/utils/logger.js +2 -2
  214. package/dist/utils/media-cache.js +190 -43
  215. package/dist/utils/npm-ops.js +43 -8
  216. package/dist/utils/restart-safety.js +14 -1
  217. package/dist/utils/system-memory.js +113 -25
  218. package/dist/utils/systemd-lifecycle.js +154 -0
  219. package/dist/utils/windows-shell-trust.js +7 -3
  220. package/dist/workbench/service.js +1 -1
  221. package/kits/docs/INDEX.md +3 -2
  222. 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
  223. package/kits/docs/channels/aun.md +1 -1
  224. package/kits/docs/evolcore/INDEX.md +9 -6
  225. package/kits/docs/evolcore/agent.md +36 -1
  226. package/kits/docs/evolcore/aid.md +45 -3
  227. package/kits/docs/evolcore/config.md +5 -2
  228. package/kits/docs/evolcore/directory.md +8 -9
  229. package/kits/docs/evolcore/group.md +2 -1
  230. package/kits/docs/evolcore/memory-tags.md +2 -0
  231. package/kits/docs/evolcore/menu-client.md +3 -3
  232. package/kits/docs/evolcore/menu-protocol.md +7 -0
  233. package/kits/docs/evolcore/model.md +3 -0
  234. package/kits/docs/evolcore/msg.md +77 -10
  235. package/kits/docs/evolcore/pay.md +34 -0
  236. package/kits/docs/evolcore/provider.md +22 -1
  237. package/kits/docs/evolcore/quota.md +54 -0
  238. package/kits/docs/evolcore/role.md +3 -0
  239. package/kits/docs/evolcore/services.md +46 -18
  240. package/kits/docs/evolcore/stats.md +2 -0
  241. package/kits/docs/evolcore/thread-chain.md +2 -0
  242. package/kits/docs/evolcore/tool-authorization.md +10 -0
  243. package/kits/docs/evolcore/trigger.md +2 -0
  244. package/kits/rules/01-overview.md +11 -32
  245. package/kits/rules/02-navigation.md +7 -0
  246. package/kits/rules/06-channel.md +3 -3
  247. package/kits/schemas/_meta.json +38 -5
  248. package/kits/schemas/agent-config.schema.20.json +24 -0
  249. package/kits/schemas/agent-config.schema.21.json +974 -0
  250. package/kits/schemas/agent-config.schema.22.json +977 -0
  251. package/kits/schemas/agent-config.schema.23.json +958 -0
  252. package/kits/schemas/daemon.schema.10.json +373 -0
  253. package/kits/schemas/daemon.schema.9.json +12 -0
  254. package/kits/schemas/defaults.schema.7.json +472 -0
  255. package/kits/schemas/providers.schema.3.json +18 -2
  256. package/kits/schemas/relation-config.schema.13.json +289 -0
  257. package/kits/skills/.switches.json +17 -1
  258. package/kits/skills/ability/SKILL.md +229 -34
  259. package/kits/skills/ability/STRUCTURE.md +333 -0
  260. package/kits/skills/ability/references/cli.md +208 -0
  261. package/kits/skills/ability/references/development.md +107 -37
  262. package/kits/skills/ability/references/management.md +106 -46
  263. package/kits/skills/ability/references/runtime-protocol.md +65 -63
  264. package/kits/skills/agent-output-cards/SKILL.md +64 -0
  265. package/kits/skills/ec-group/SKILL.md +8 -6
  266. package/kits/skills/ec-group/TASK.md +186 -0
  267. package/kits/skills/ec-group/WORKLOG.md +180 -0
  268. package/kits/skills/ec-group-collaboration/SKILL.md +3 -3
  269. package/kits/skills/ec-pay/SKILL.md +101 -0
  270. package/kits/skills/ec-pay/references/pay-cli.md +110 -0
  271. package/kits/skills/ec-provider/SKILL.md +58 -9
  272. package/kits/skills/{ec-service-proxy → ec-proxy}/SKILL.md +8 -5
  273. package/kits/skills/ec-service-call/SKILL.md +135 -0
  274. package/kits/skills/ec-service-pack/SKILL.md +277 -0
  275. package/kits/skills/ec-trigger/SKILL.md +1 -1
  276. package/kits/templates/memory-consolidation/notes.md +2 -2
  277. package/kits/templates/memory-consolidation/workflow.md +46 -0
  278. package/kits/templates/roles/visitor.json +1 -0
  279. package/kits/templates/system-fragments/channel.md +13 -4
  280. package/kits/templates/system-fragments/commands.md +5 -3
  281. package/kits/templates/system-fragments/directory-contacts.md +3 -4
  282. package/kits/templates/system-fragments/reply.md +1 -0
  283. package/kits/templates/system-fragments/session.md +1 -1
  284. package/kits/templates/system-fragments/thread.md +27 -128
  285. package/kits/templates/system-fragments/venue.md +27 -0
  286. package/package.json +4 -5
  287. package/scripts/agent-template/inspect.mjs +79 -29
  288. package/scripts/agent-template/overlay.mjs +20 -2
  289. package/scripts/agent-template/shared/common.mjs +24 -6
  290. package/scripts/agent-template/shared/team-schema.json +23 -5
  291. package/scripts/agent-template/shared/template-contract.mjs +107 -17
  292. package/scripts/agent-template/shared/template-package.mjs +254 -29
  293. package/scripts/agent-template/shared/template-runtime.mjs +145 -2
  294. package/scripts/agent-template/shared/template.mjs +67 -9
  295. package/scripts/agent-template/team-pack.mjs +132 -41
  296. package/scripts/agent-template/team-preview.mjs +249 -5
  297. package/kits/docs/aun/ABILITY_CALLING.md +0 -280
  298. package/kits/docs/evolcore/ability.md +0 -185
  299. package/kits/skills/ability/references/calling.md +0 -56
  300. package/kits/skills/ability/references/contract-checklist.md +0 -37
  301. package/kits/skills/ability/references/recovery.md +0 -27
  302. /package/dist/{core/capability/providers → agents/gemini}/gemini-capability-provider.js +0 -0
@@ -0,0 +1,110 @@
1
+ # ec pay CLI 与字段全表
2
+
3
+ 只在 SKILL.md 的骨架不够用、或命令报错要查细节时读这份。
4
+
5
+ ## 命令面
6
+
7
+ ```bash
8
+ ec pay request --spec-file "$TMPDIR/payment-request.json"
9
+ ec pay status <request-id>
10
+ ec pay verify <request-id>
11
+ ec pay refresh <request-id>
12
+ ec pay cancel <request-id>
13
+ ec pay update <request-id> --spec-file "$TMPDIR/payment-update.json"
14
+ ec pay complete <request-id> --event-id <event-id>
15
+ ```
16
+
17
+ 全部输出 JSON,可显式 `--format json`。托管命令保留当前委托环境,不能指定 self、付款人、另一话题或其它 AID。
18
+ `request-id` = `pay_` + 32 位十六进制;`event-id` = `payjob_` + 32 位十六进制。
19
+
20
+ `status` 返回 `payment`、`state_version`、`card_message_id`、`delivery`、`pending_events`。
21
+ `sent` = 已获传输消息 ID,`queued` = 待可靠发送,**二者都不是已付款**。
22
+ `pending_events` 每项含 `event_id`、`kind` 和事件创建时版本。
23
+
24
+ `verify` / `refresh` 只安排持久任务,命令返回不代表网站操作已完成。
25
+ `status` 用于读状态,不代替原网站核验。
26
+
27
+ ## request 全字段
28
+
29
+ | 字段 | 说明 |
30
+ |---|---|
31
+ | `idempotency_key` | 必填建议。同 session 同 key 重试返回同一请求;同 key 换参数报 `IDEMPOTENCY_CONFLICT`。省略时按当前会话、来源消息和 spec 路径生成回退 key |
32
+ | `source.origin` | 无凭据、无路径、无查询的 HTTPS origin |
33
+ | `source.order_id` / `purpose` | 订单号与用途;有订单号时后续核验必须回同样值 |
34
+ | `source.merchant` | 可选 `{name, source}` |
35
+ | `product.title` / `description` / `quantity` | 商品描述 |
36
+ | `product.image_attachment_index` | 可选商品图下标;更新 media 时必须保留该下标 |
37
+ | `amount.value_minor` | 最小币种单位安全整数;未知用 `null` |
38
+ | `amount.currency` | 未知用 `null` |
39
+ | `amount.source` | `page_text` / `page_dom` / `qr_payload` / `inferred` / `unknown` |
40
+ | `attachments[].file_path` | 绝对路径,或相对当前项目。**不要写进发送 payload** |
41
+ | `method_options[].provider` | `wechat` / `alipay` |
42
+ | `method_options[].availability` | `ready` / `requires_site_switch` / `unavailable` / `unknown` |
43
+ | `method_options[].qr_ids` | 仅 `ready` 时可非空,且必须指向真实存在的码 |
44
+ | `method_options[].evidence` | `{source, text}`。`ready` 不接受 `inferred` / `unknown` 证据 |
45
+ | `qr_codes[].id` / `attachment_index` / `providers` / `expires_at_ms` | 码与图片绑定 |
46
+ | `qr_codes[].raw_payload` | 可选;给了就必须与图片实际解码内容一致 |
47
+ | `order_expires_at_ms` | 网站订单期限,未知 `null` |
48
+
49
+ 上限:最多 4 张 PNG / JPEG / WebP,每张 ≤ 4 MiB、≤ 1600 万像素。命令实际解码所有被引用二维码。
50
+
51
+ `expires_at_ms`(请求级)省略默认十分钟;显式值须在当前至未来 24 小时内。系统时限与网站时限分开,不自动续期,
52
+ 也不得把系统时限称作网站时限。
53
+
54
+ 去重:同网站同订单号已有请求时拒绝新建(`ORDER_EXISTS`),改用原请求 `verify` / `refresh`。
55
+ 每 Agent 最多 1000 份请求。
56
+
57
+ ## update 字段
58
+
59
+ | 字段 | 说明 |
60
+ |---|---|
61
+ | `expected_state_version` | 必填,来自最近一次 `status`,不符报 `STALE_VERSION` |
62
+ | `event_id` | 必填,来自 `status` 的 `pending_events` |
63
+ | `verification.order_state` | `pending` / `paid` / `failed` / `unknown` |
64
+ | `verification.source` | `website_order` / `website_success_page` / `payment_api` |
65
+ | `verification.checked_at_ms` | 不得早于本事件,不得比当前时间晚 30 秒以上 |
66
+ | `verification.order_id` | 原请求有订单号时必须一致 |
67
+ | `verification.evidence` | 人可读的核验依据 |
68
+ | `media` | 可选 `{attachments, method_options, qr_codes}`,结构与 request 相同 |
69
+
70
+ `media` 规则:`verify` 事件不能替换码。切渠道或 `refresh` 仅在核验为 `pending` 且请求 `active` 时可换码。
71
+ 切指定渠道成功后该渠道必须 `ready`。已取消 / 到期不能替换码,但仍可提交已发生的付款核验。
72
+
73
+ 客户端动作不能直接写 `paid`。只有当前 Owner 原会话中有效委托的 update 能提交网站观察证据;
74
+ 这表示 Agent 对原网站的核验结果,不是支付平台签名证明。
75
+
76
+ ## 全部错误码
77
+
78
+ | 码 | 含义 |
79
+ |---|---|
80
+ | `INVALID_ARGUMENT` | 参数形态不对,按 `--help` 修正 |
81
+ | `NOT_AUTHORIZED` | Ownership 已变,或请求属于另一会话 |
82
+ | `RECORD_UNAVAILABLE` | 请求记录不可读 |
83
+ | `ACTION_IN_PROGRESS` | 已有未完成的付款操作 |
84
+ | `ORDER_PAID` | 订单已付,不能再改码 |
85
+ | `ORDER_EXISTS` | 同订单号已有请求 |
86
+ | `VERIFICATION_REQUIRED` | 缺原订单核验 |
87
+ | `INVALID_VERIFICATION` | 核验与原订单或待办事件不匹配 |
88
+ | `STALE_VERSION` | `expected_state_version` 过期 |
89
+ | `INVALID_EVENT` | 事件不存在、已消费,或状态不允许该动作 |
90
+ | `INVALID_ACTION` | 卡片动作在当前状态不可用 |
91
+ | `QR_INVALID` | 码解码失败、与 raw_payload 不符,或码不可用 |
92
+ | `METHOD_NOT_READY` | 所选渠道仍无可用码 |
93
+ | `IDEMPOTENCY_CONFLICT` | 同 key 换了参数 |
94
+ | `REQUEST_EXPIRED` | 请求超期 |
95
+ | `CAPACITY_REACHED` | 达到每 Agent 1000 份请求上限 |
96
+ | `CHANNEL_UNAVAILABLE` | Agent 的 AUN 渠道不可用 |
97
+
98
+ ## 持久性与限额
99
+
100
+ Agent 的 `data/payments/` 保存请求、消息绑定、动作回执、事件和待发送记录,属 daemon 保护状态,**不能直接编辑**。
101
+ 后台每 15 秒协调未提交消息 / 任务及请求到期;可靠队列和原事件编号防止重启重复入队。
102
+ Owner / Ownership 版本变化后停止旧请求的动作、发送和恢复,不改投另一话题。
103
+
104
+ 每请求累计 500 个 App 动作或 1500 个投递记录后,停止接收新的 App 动作 / 同步,不删除已有记录;
105
+ CLI 原任务核验仍可完成。App 无响应按超时处理并停用入口。
106
+
107
+ 第一版不自动清理历史订单,不提供退款、个人转账或自动扣款。
108
+ 队列去重不等于外部网站支持 exactly-once——网站侧副作用仍需核对是否已执行。
109
+
110
+ App 对接见仓库 `docs/evo-app-pay-integration-v1.md`(仅开发时需要)。
@@ -5,7 +5,7 @@ description: >-
5
5
  查看当前用的 Provider 与模型、查看模型信息与价格、切换模型或切换模型服务商。
6
6
  当用户说「配置 provider」「接入某家的 API」「换 key / 换地址」「这个 key 能用吗」
7
7
  「现在用的什么模型」「切到某个模型」「换一家供应商」「模型多少钱 / 上下文多大」时使用。
8
- 不适用于:Ability 插件(用 ec ability)、本地服务代理(用 ec-service-proxy)。
8
+ 不适用于:Ability 插件(用 ec ability)、本地服务代理(用 ec-proxy)。
9
9
  license: MIT
10
10
  ---
11
11
 
@@ -55,6 +55,21 @@ baseagents = {"claude":{"provider":"provider-1","model":"deepseek-v4.1-flash","e
55
55
  非托管宿主终端可用内联参数或 TTY;托管环境即使 fullaccess 也只用 --file。
56
56
  没有合适模板时使用下面的完整 Provider JSON。
57
57
 
58
+ ### 模板输入文件写什么
59
+
60
+ `--template` 的输入文件是一个 JSON 对象,合法键只有 `apiKey`、`name`、`serviceTypes`、`inputs`、`templateRevision`:
61
+
62
+ | 情形 | 输入文件 |
63
+ |------|---------|
64
+ | `fields: []`(如 `deepseek-api`) | 只填**顶层** `apiKey`:`{ "apiKey": "sk-..." }` |
65
+ | `fields: [...]` | 每个字段的 `name` 写进 `inputs`:`{ "apiKey": "sk-...", "inputs": { "<name>": "<值>" } }` |
66
+ | 只想要部分服务 | 加 `serviceTypes: ["claude", "text"]`,不写则按模板默认 |
67
+
68
+ > `apiKey` 和 `inputs` 是**平级**的两个键,`apiKey` 不能写进 `inputs`——写进去会报
69
+ > `Unknown Provider template field`,而不是提示缺密钥。
70
+
71
+ 没有合适模板时使用下面的完整 Provider JSON。
72
+
58
73
  1. 写 Provider JSON 到临时文件。
59
74
  2. `ec provider create --file <绝对路径>`
60
75
 
@@ -146,12 +161,15 @@ ec model list [--format json] # 可选模型
146
161
 
147
162
  ```bash
148
163
  # Provider 已注册:用注册表里的密钥实测
149
- node "<技能目录>/scripts/check-model.mjs" --provider <id> --list-models
164
+ node "<技能目录>/scripts/check-model.mjs" --provider <id> --service <服务类型> --list-models
150
165
 
151
166
  # Provider 还没注册:用外部传入的地址和密钥
152
167
  node "<技能目录>/scripts/check-model.mjs" --base-url <url> --api-key <key> --style openai-compatible --list-models
153
168
  ```
154
169
 
170
+ **一次只测一个服务。** 不写 `--service` 时按 `claude` → `text` → 模板声明顺序的第一个回落,
171
+ 返回里的 `service` 字段就是本次实测的服务;要覆盖多个服务就逐次指定。
172
+
155
173
  统一使用 check-model.mjs:--provider 与 --base-url/--api-key 两种连接来源不能混用。
156
174
  两种方式均返回真实目录中的模型 ID,目录成功不等于模型推理成功。已注册 Provider 的脚本复用 Core
157
175
  解析 service.path、catalogPath、服务独立凭据及模型策略,支持 --service 明确指定目标服务。
@@ -179,10 +197,14 @@ node "<技能目录>/scripts/check-model.mjs" --provider <provider-id> --service
179
197
 
180
198
  | 目标 | 命令 |
181
199
  |------|------|
182
- | 换模型(推荐) | `ec model use <model-id> --self <AID>` |
183
- | 同时设推理强度 | `ec model use <model-id> --effort high --self <AID>` |
200
+ | 换模型(推荐) | `ec model use <model-id>` |
201
+ | 同时设推理强度 | `ec model use <model-id> --effort high` |
184
202
  | 换 Provider(Agent 级) | `ec config set baseagents.<base>.provider <provider-id> --self <AID>` |
185
- | 清除 Agent 级设置 | `ec model reset --self <AID>` |
203
+ | 清除 Agent 级设置 | `ec model reset` |
204
+
205
+ > **托管会话不要给 `ec model` 写操作加 `--self`。** 它在托管会话里只作用于当前 Agent,
206
+ > `--self <本端 AID>` 等同省略,指向其他 Agent 会返回 `NOT_ALLOWED`。
207
+ > `ec config set` 相反:写入必须带 `--self <AID>` 或 `--default`。
186
208
 
187
209
  - `<base>` 取 `claude` / `codex` / `gemini` / `ecagent`,必须与实际基座一致。
188
210
  - **换 Provider 时模型 id 必须属于该 Provider**,否则调用直接失败;`provider` 和 `model` 要一起改。
@@ -194,15 +216,42 @@ node "<技能目录>/scripts/check-model.mjs" --provider <provider-id> --service
194
216
  # 1. 先测通
195
217
  node "<技能目录>/scripts/check-model.mjs" --provider provider-91036436 --model deepseek-flash
196
218
 
197
- # 2. 再切换
219
+ # 2. 再切换(先绑 provider,再改 model;反过来会留下 model 不属于 provider 的窗口)
198
220
  ec config set baseagents.claude.provider provider-91036436 --self <AID>
199
- ec model use deepseek-flash --self <AID>
221
+ ec model use deepseek-flash
200
222
 
201
223
  # 3. 确认
202
- ec model current --self <AID>
224
+ ec model current
225
+ ec model check
203
226
  ```
204
227
 
205
- ## 七、坑与边界
228
+ 切换后如果模型不可用,按记录的原值反向设置即可回滚,然后重跑一次 `ec model check`:
229
+
230
+ ```bash
231
+ ec config get baseagents --self <AID> # 切换前先记录原 provider/model/effort
232
+ ec config set baseagents.claude.provider <原 provider-id> --self <AID>
233
+ ec model use <原 model-id>
234
+ ```
235
+
236
+ ## 七、配置兜底(fallback)
237
+
238
+ 主模型不可用时按 `baseagents.<base>.fallback` 依次降级,**最多 3 项**,每项必须同时给出
239
+ `provider` / `model` / `effort`(降级可能换用不同供应商的不同模型)。
240
+
241
+ Agent 级可写:
242
+
243
+ ```bash
244
+ ec config set baseagents.claude.fallback \
245
+ '[{"provider":"provider-91036436","model":"deepseek-flash","effort":"xhigh"}]' \
246
+ --self <AID>
247
+ ```
248
+
249
+ - 值必须是 JSON 数组;空数组 `[]` 表示清除降级链。
250
+ - `effort` 必须出现在该模型目录的支持列表里,否则这条候选会被**静默丢弃**(`reason: unsupported_effort`)——
251
+ 配置写成功不等于一定会降级。
252
+ - 全局默认的降级链在 `~/.evolcore/agents/defaults.json`,只能用编辑器改,改完跑 `ec config validate --default`。
253
+
254
+ ## 八、坑与边界
206
255
 
207
256
  - **模型 id 照抄供应商返回的**,不要拿本地别名去试。反例:DeepSeek 官方只接受
208
257
  `deepseek-flash` / `deepseek-v4-pro`,传 `deepseek-v4.1-flash` 直接 400。
@@ -1,13 +1,16 @@
1
1
  ---
2
- name: ec-service-proxy
2
+ name: ec-proxy
3
3
  description: >-
4
- 查询和管理当前 EvolCore daemon 的本地服务与 AUN ServiceProxy。用户询问代理状态、
5
- 服务是否在线,或要求创建、修改、发布、撤销、启动、停止、重启受管服务时使用。
6
- 不用于设计或实现新的 Ability Provider,也不用于 Menu 协议、Agent 创建或 npm 发版。
4
+ 查询和管理当前 EvolCore daemon 的本地服务与 AUN ServiceProxy(ec proxy 命令)。用户
5
+ 询问代理状态、服务是否在线,或要求创建、修改、发布、撤销、启动、停止、重启受管服务时
6
+ 使用。不用于设计或实现新的 Ability Provider,也不用于 Menu 协议、Agent 创建或 npm 发版。
7
+ 也不用于 ec services 的服务包机制(pack.json / services.* / 对端调你):建包用
8
+ ec-service-pack,调别人用 ec-service-call。两者说的「服务」是不同东西——本 skill 管的是
9
+ daemon 的 services[] 与 AUN ServiceProxy 转发,不涉及 pack.json。
7
10
  license: MIT
8
11
  ---
9
12
 
10
- # EC ServiceProxy
13
+ # EC Proxy
11
14
 
12
15
  用 ec proxy 管理当前 daemon 的 services 配置、AUN 代理发布,以及明确标记为 managed 的本地服务。
13
16
  先查询当前状态;写操作必须用查询所得的 configRev 做 CAS。不要直接编辑 daemon.json。
@@ -0,0 +1,135 @@
1
+ ---
2
+ name: ec-service-call
3
+ description: >-
4
+ 调用对端 Agent 提供的 services.* 服务并拿到结果。用户说"问问 XX 那边能不能…""调一下 XX 的
5
+ 服务""对端有什么服务/接口""这个 data 该塞什么""服务调用超时/NO_RESULT/NOT_AUTHORIZED/
6
+ 收不到结果"时使用。不适用于本机建服务包(用 ec-service-pack)、到点执行(用 ec-trigger)、
7
+ 广播(用事件中心),也不适用于本机 HTTP 服务与 AUN 代理(用 ec-proxy)。
8
+ license: MIT
9
+ ---
10
+
11
+ # EC 服务调用:发现、调用、判失败
12
+
13
+ 服务调用是**点对点 RPC**:要结果、会丢、不补投。跟普通消息最大的区别是**对端离线时
14
+ 请求到 TTL 就消失**,重连也拉不到。
15
+
16
+ ## 一、先发现,再调用
17
+
18
+ ```bash
19
+ ec services describe --aid <对端AID> # 对方有什么
20
+ ec services describe --aid <对端AID> --type <type> # 单个服务的细节
21
+ ec services schema --aid <对端AID> --type <type> # 请求 schema
22
+ ec services call --aid <对端AID> --type <type> --data '<json>' # 调用
23
+ ```
24
+
25
+ `describe` 的产出里最该看的是 `handlers[].name` / `handlers[].description`——
26
+ **`pack.json` 不声明入参结构,`data` 契约只写在这里**。没有 description 就只能靠 type 名猜。
27
+
28
+ 还有第三种读物:`services.skill`,返回一段可直接读的用法说明(对端 Agent 视角写的)。
29
+ 用 `describe --aid <对端AID> --type <type>` 拿不到信息时值得一问。
30
+
31
+ ## 二、参数:谁是目标,谁是发送方
32
+
33
+ `--aid` 在 `ec services` 家族里**一律指被调用/被操作的那个 agent**(与 `status --aid`、
34
+ `pack add --aid` 一致)。对端调用另有一个 `--as` 指定**发送身份**:
35
+
36
+ | 参数 | 含义 | 缺省 |
37
+ | --- | --- | --- |
38
+ | `--aid` | **被调用方**(对端 AID) | 必填 |
39
+ | `--type` | 服务 type | 必填(`--service` 是历史别名) |
40
+ | `--as` | **发送身份**:本机以哪个 agent 的 AUN 通道发出 | 托管会话取会话身份;宿主终端回落到 daemon AID |
41
+
42
+ **托管会话里不用写 `--as`**——daemon 从会话身份推出。宿主终端没有会话身份,会回落到
43
+ daemon 自己的 AID;而 daemon AID 通常**没有 AUN 通道**,于是报
44
+ `NOT_CONFIGURED: no AUN channel is connected for <daemonAid>`,这时补 `--as <有通道的AID>`
45
+ 即可。指定了但那个 AID 没有通道,也是同一个错。
46
+
47
+ > 不能调自己:`--aid` 指向本端 AID 会直接被拒(`cannot call self`),
48
+ > 因为入站侧没有分支会应答自调用,等下去只会得到像对端故障的 `NO_RESULT`。
49
+
50
+ ## 三、调用的三个必知语义
51
+
52
+ **1. 默认等 12 秒,超时不重试。**
53
+
54
+ ```bash
55
+ ec services call --aid alice.agentid.cn --type services.order.create --data '{"sku":"A-1","qty":2}'
56
+ ```
57
+
58
+ | 选项 | 作用 |
59
+ |---|---|
60
+ | `--timeout 5` | 自定等待时长(秒;也接受 `30s` / `2m`) |
61
+ | `--encrypted` | 加密调用,回复也加密 |
62
+
63
+ 退出码:`0` 成功;`1` 失败(业务失败或传输失败);**`2` = `NO_RESULT`,可能已执行**。
64
+ 脚本跑完但报业务失败(`ok:false`)时也是 `1`,所以 `cmd && next` 不会被骗过去。
65
+
66
+ **2. 请求只活一个调用窗口。** TTL 由你的等待时长推导,到期即从网关消失。
67
+ 所以「对端不在线」和「对端不服务」在你的视角上是同一种结果:超时。
68
+
69
+ **3. 超时后不要直接重发。** 用**同一个 `request_id`** 重试在结果缓存有效期内不重跑脚本;
70
+ 默认保留 15 秒,更长调用窗口延至截止后 3 秒,缓存过期后重发可能重新执行。CLI 每次调用都会自动生成新的
71
+ `request_id`——**要利用幂等必须由能自定 `request_id` 的调用方(SDK / 脚本)来发**,
72
+ `ec services call` 做不到。
73
+
74
+ ## 四、结果长什么样
75
+
76
+ 同 AID 通道自测时,外层是 daemon 的请求记录,`response` 才是对端原文:
77
+
78
+ ```json
79
+ {
80
+ "request_id": "req_…",
81
+ "state": "completed",
82
+ "message_id": "…",
83
+ "target": "<目标AID>",
84
+ "response": {
85
+ "type": "services.order.create.result",
86
+ "request_id": "req_…",
87
+ "ok": true,
88
+ "data": { "order_id": "O-1" }
89
+ }
90
+ }
91
+ ```
92
+
93
+ - **回复 type 固定是「请求 type + `.result`」**,不会变成别的。
94
+ - 业务失败:同 type、`ok:false`、`error.code` + `error.message`。
95
+ - `data` 是**纯调用方正文**,不含 `chatmode` / `client_signature` / `thread_id` / `topicName`
96
+ ——服务调用没有话题概念。
97
+
98
+ ## 五、失败码怎么读
99
+
100
+ | 码 | 含义 | 该怎么办 |
101
+ |---|---|---|
102
+ | `NO_RESULT` | 没等到结果(退出码 2) | **可能已执行**。别直接重发,先确认对方状态 |
103
+ | `NOT_AUTHORIZED` | 你不是对方的联系人(或不在 `rules.allow`) | 走 `ec directory request` 找对方 Owner,别反复调 |
104
+ | `UNKNOWN_TYPE` | 对方没有这个 type(包 `unmatched: reject` 时才回) | 重新 `describe` 看准确 type |
105
+ | `RATE_LIMITED` | 超限,看 `retry_after` | 等够秒数再调 |
106
+ | `TIMEOUT` | 对方脚本超时(是**对方的**超时,不是你等待超时) | 对方脚本太慢,不是网络问题 |
107
+ | `HANDLER_PROTOCOL` | 脚本末行不是合法 JSON | 对方脚本 bug |
108
+ | `SCRIPT_OUTPUT_LIMIT` | 对方脚本输出超 1 MiB 被杀 | 同上 |
109
+ | `NOT_CONFIGURED` | 本端没有 AUN 通道 | 补 `--aid <调用方AID>` |
110
+ | `INVALID_ARGV` | 参数问题,含 `cannot call self` | 看错误原文 |
111
+
112
+ **未准入时「有没有回包」不是判断服务是否存在的依据**:未准入来源永远得到同一条与请求
113
+ 内容无关的拒绝,且 24 小时只回一次,之后静默。所以**别用反复调用探测对端有什么**——
114
+ 用 `describe`(它对未准入只给空壳清单,也不暴露细节)。
115
+
116
+ 被拉黑(`deny`)的回包与「未准入」**完全相同**,这是故意的:否则两者可区分,
117
+ 就成了探测信道。
118
+
119
+ ## 六、什么时候该怀疑"不是服务的问题"
120
+
121
+ | 现象 | 先查 |
122
+ |---|---|
123
+ | 一直 `NO_RESULT` | 对端是否在线;`--aid` 给的调用方有没有通道 |
124
+ | `NOT_CONFIGURED` | `--aid` 是否指到了没有 AUN 通道的 host AID |
125
+ | `cannot call self` | 目标和 `--aid` 是不是同一个 AID |
126
+ | 对端说"没收到" | 你是 volatile 发的,对方离线期间不会补投——不是消息丢了,是设计如此 |
127
+ | 对方有 `services.*` 但调不通 | 对方的 `enabled` 总闸、以及你的 AID 在不在它 `rules` 里 |
128
+
129
+ ## 七、不要做的事
130
+
131
+ 1. **不要对没有幂等的操作做"超时重发"**。超时后结果未知,重发可能执行两次。
132
+ 2. **不要用服务调用做广播**。点对点,一次一个对端;广播用事件中心。
133
+ 3. **不要指望回复带话题**。要关联上下文自己记 `request_id`。
134
+ 4. **不要拿"没回包"当探测手段**。未准入与拉黑的回包被刻意做成不可区分。
135
+ 5. **不要反复调被拒的服务**。它会静默,你的重试不会有更多信息。
@@ -0,0 +1,277 @@
1
+ ---
2
+ name: ec-service-pack
3
+ description: >-
4
+ 给本 Agent 建服务包(pack.json + 处理脚本),让对端能调用并经你回结果。用户说"给某个
5
+ 服务做个接口""对外提供 XX 服务""让对端调到我的 XX 能力""建个服务包/pack.json""帮我把这段
6
+ 逻辑暴露成 services.* ""服务包为什么没生效/skipped/invalid/调不通"时使用。不适用于到点
7
+ 执行(用 ec-trigger)、广播通知(用 event-center)、常驻本地进程与 AUN 代理(用
8
+ ec-proxy),也不适用于调用别人的服务(用 ec-service-call)。
9
+ license: MIT
10
+ ---
11
+
12
+ # EC 服务包:建、装、验
13
+
14
+ **本 skill 只讲怎么把本 Agent 变成一个可被调用的服务节点。** 字段级约束看
15
+ `$KITS_DOCS/evolcore/services.md` 与 `docs/services/schema/pack.schema.json`;
16
+ 参数看 `ec services --help`。
17
+
18
+ **建错九成是下面四件事之一**:`requires` 与名片不匹配、`listen.type` 与对端发的字符串
19
+ 不一致、`reply.allowed` 没开、新包没有被 reload 上。
20
+
21
+ ## 〇、先判断该不该做成服务
22
+
23
+ | 用户要的 | 用什么 |
24
+ |---|---|
25
+ | 对端发消息 → 我跑确定性逻辑 → **回结果** | **服务(本 skill)** |
26
+ | 到点执行(每天 9 点、每 30 分钟) | `ec-trigger` 技能 |
27
+ | 我主动广播给很多人 | `ec events`(事件中心),不是服务 |
28
+ | 本机起一个长期跑的 HTTP 服务并对外代理 | `ec-proxy` 技能 |
29
+
30
+ 一句话:**服务是点对点调用,有应答,且会丢**(volatile,超时即失败,不补投)。
31
+
32
+ ## 一、目录与硬约束
33
+
34
+ ```
35
+ $AGENT_DIR/services/
36
+ ├── services-config.json # 总闸 + 限流 + 准入规则 + host 段
37
+ └── <包名>/
38
+ ├── pack.json
39
+ ├── scripts/<处理脚本>
40
+ ├── ledger.jsonl # daemon 写
41
+ └── logs/ # daemon 写
42
+ ```
43
+
44
+ - 包名用小写横线英文(`order`、`inventory`),**目录名才是身份**,`pack.json` 的 `name` 只是展示名。
45
+ - `services/` 是 **L 类受保护路径**:托管会话里 `Write` / `cp` 直接写会被拒。
46
+ **正确做法是写到工作区,再 `pack add` 让 daemon 代写。**
47
+
48
+ ```bash
49
+ # ① 在工作区写源目录
50
+ <工作区>/packs/hello/{pack.json,scripts/*.mjs}
51
+ # ② 装(daemon 代写进 agents/<aid>/services/)
52
+ ec services pack add hello --from <工作区>/packs/hello --aid "$SELF"
53
+ # ③ 验
54
+ ec services status --aid "$SELF" && ec services types --aid "$SELF"
55
+ ```
56
+
57
+ - **没有覆盖安装**:已存在时报 `PACK_ALREADY_EXISTS`,先 `pack remove` 再装。
58
+ - `pack enable|disable <包>` 改的是 `pack.json` 的 `enabled`(单包开关),
59
+ 与 AID 级总闸 `ec services enable|disable` 是两个层级,别混。
60
+
61
+ ## 二、`pack.json` 最小形态
62
+
63
+ ```json
64
+ {
65
+ "v": 1,
66
+ "name": "订单受理",
67
+ "description": "订单受理相关的全部服务",
68
+ "requires": { "type": ["services", "agent"], "exttype": "order" },
69
+ "listen": [
70
+ {
71
+ "type": "services.order.create",
72
+ "handler": {
73
+ "script": "scripts/on-create.mjs",
74
+ "runtime": "node",
75
+ "timeoutMs": 15000,
76
+ "name": "下单",
77
+ "description": "创建订单。data: {sku, qty},返回 order_id"
78
+ }
79
+ }
80
+ ],
81
+ "reply": { "allowed": true }
82
+ }
83
+ ```
84
+
85
+ | 字段 | 要点 |
86
+ |---|---|
87
+ | `requires` | **必填**,匹配的是**本机名片**(`type`/`exttype`),不是消息。不匹配 = 包 `skipped`,不是报错 |
88
+ | `listen[].type` | 必须是 `services[.<段>.<段>]`,末段可写 `*`;末段不能是 `result` |
89
+ | `handler.script` | 必须在 `scripts/` 下,禁绝对路径、`..`、反斜杠、符号链接 |
90
+ | `handler.runtime` | `node` / `python` / `bash` / `powershell`;省略按扩展名推断 |
91
+ | `handler.timeoutMs` | **缺省 10000**,范围 [1000, 300000]。**默认值刻意短于调用方 12 秒的等待期** |
92
+ | `handler.name`/`description` | 可选但**强烈建议**:这是 `data` 契约的唯一声明渠道,对端靠 `describe`/`skill` 读到才知道该塞什么 |
93
+ | `handler.mode` | `spawn`(默认)/ `resident`。**默认别用 resident**,见第七节 |
94
+ | `reply.allowed` | **缺省 false**。不开就只有执行记录,调用方永远收不到结果 |
95
+
96
+ `requires` 怎么写:
97
+
98
+ | 写法 | 含义 |
99
+ |---|---|
100
+ | `{"type":"services","exttype":"order"}` | 只在名片 `type=services`+`exttype=order` 时生效 |
101
+ | `{"type":["services","agent"],"exttype":"order"}` | services 和 agent 都生效 |
102
+ | `{"type":"*","exttype":"*"}` | 完全放开 |
103
+
104
+ **兼职是推荐做法**:不用为提供服务另开一个 AID,名片保持 `type=agent` 即可。
105
+
106
+ ## 三、脚本契约(这是最容易写错的地方)
107
+
108
+ 脚本**从 stdin 读一个 JSON 到 EOF**,**最后一行 stdout 输出一个 JSON**。
109
+
110
+ ```js
111
+ let raw = '';
112
+ process.stdin.setEncoding('utf8');
113
+ process.stdin.on('data', c => { raw += c; });
114
+ process.stdin.on('end', () => {
115
+ const { message } = JSON.parse(raw);
116
+ // message.data 是调用方正文;message.from 是调用方 AID;message.type 是 type
117
+ console.log(JSON.stringify({
118
+ outcome: 'success',
119
+ data: { order_id: 'O-1', sku: message.data.sku },
120
+ }));
121
+ });
122
+ ```
123
+
124
+ 输入形状:
125
+
126
+ ```json
127
+ {
128
+ "v": 1,
129
+ "service": { "name": "订单受理", "dir": "…/services/order" },
130
+ "message": {
131
+ "type": "services.order.create",
132
+ "requestId": "01J…",
133
+ "from": "alice.agentid.cn",
134
+ "receivedAt": 1794115720000,
135
+ "encrypted": false,
136
+ "data": { "sku": "A-1" }
137
+ },
138
+ "agent": { "aid": "self.agentid.cn", "dir": "…", "type": "services", "exttype": "order" },
139
+ "paths": { "ledger": "…/ledger.jsonl", "logs": "…/logs" }
140
+ }
141
+ ```
142
+
143
+ 输出三选一(**最后一行**):
144
+
145
+ ```json
146
+ {"outcome":"success","data":{...}}
147
+ {"outcome":"error","error":{"code":"OUT_OF_STOCK","message":"库存不足"}}
148
+ {"outcome":"noop"}
149
+ ```
150
+
151
+ 必须知道的几条:
152
+
153
+ - **没有 `threadId`/`topicName`/`chatmode`**——服务调用不是聊天。
154
+ - `paths` 只是定位信息,**脚本读写不了**(沙箱对服务目录 EPERM)。要留痕就写 stdout。
155
+ - **不要自己发回复**。输出 `outcome`,daemon 按 `<请求type>.result` 派生并发。
156
+ - 回复 `type` 自动派生:`services.order.create` → `services.order.create.result`。
157
+ - **输出上限 stdout+stderr 合计 1 MiB,超出直接杀掉进程并返回 `SCRIPT_OUTPUT_LIMIT`**,不是截断。
158
+ - 脚本能读到的环境变量:`EC_SELF_AID` / `EC_SELF_TYPE` / `EC_SELF_EXTTYPE` / `EC_PACK_DIR` /
159
+ `EC_SERVICE` / `EC_REQUEST_ID` / `EC_FROM` / `EC_MESSAGE_ID` / `EC_ENCRYPTED`。
160
+ 其余凭据类变量与全部 `EVOLCORE_*` 已被清理。
161
+
162
+ **Windows 沙箱**:`runtime` 必须是原生可执行文件(`node` → `node.exe`),脚本扩展名不受限
163
+ (`.mjs`/`.js`/`.cjs` 都行)。沙箱依赖 `@openai/codex`,没装时返回 `SCRIPT_SANDBOX_UNAVAILABLE`(126)。
164
+
165
+ ## 四、装完必须验的四项
166
+
167
+ ```bash
168
+ ec services status --aid "$SELF" # packs[].status 必须是 active
169
+ ec services types --aid "$SELF" # 出现你声明的 type
170
+ ec services doctor --aid "$SELF" # 无 error
171
+ ec services pack list --aid "$SELF"
172
+ ```
173
+
174
+ | 状态 | 含义 |
175
+ |---|---|
176
+ | `active` | 正常 |
177
+ | `skipped` | `requires` 与本机名片不匹配。**合法状态,不是错误**——所以拷包给别人是安全的 |
178
+ | `invalid` | 配置错误,`doctor` 会说明哪一条 |
179
+ | `disabled` | `pack.json` 的 `enabled=false` |
180
+
181
+ **自测怎么做**:`ec services call` **禁止调本机自身 AID**(`cannot call self`),所以不能
182
+ "自己调自己"来验证。验证靠两种:
183
+
184
+ 1. **别的方法**:`ec services types` 里有你的 type、`doctor` 无错、装包后 `status=active`;
185
+ 2. **真调**:让另一个有 AUN 通道的 Agent 调你,或由对端会话发起。
186
+
187
+ > 别把「`ec services call` 报 `cannot call self`」当成服务坏了——那是前置拒绝。
188
+
189
+ ## 五、回复、准入与限流
190
+
191
+ - **回复由 daemon 代发**,加密态跟随来信,不带话题信息,自动带 `request_id` 与 `replyToMessageId`。
192
+ - 服务调用**认联系人配置**,准入判定在包匹配**之前**:未准入的调用不会触达包、不会起脚本沙箱。
193
+ 陌生来源第一次收到一条与请求内容无关的 `NOT_AUTHORIZED`,24 小时内只回一次,之后静默。
194
+ **不会自动给你建联系人申请**。
195
+ - 内置查询按「返回体里有没有内部结构」分级:`ping` 全开;`list`/`describe`(不带 service)
196
+ 降级空壳;带 service 的统一拒绝。
197
+ - 限流按来源 AID 独立计:业务 `50/分、1000/时`,内置 `20/分、200/时`,超限 `RATE_LIMITED` + `retry_after`。
198
+
199
+ 要放开给特定对端,按 type 加规则(写在 `services-config.json`,用命令改):
200
+
201
+ ```bash
202
+ ec services rules show # 看全部
203
+ ec services rules add services.order.create buyer.agentid.cn
204
+ ec services rules add services.order.create spam.agentid.cn --deny
205
+ ec services rules remove services.order.create spam.agentid.cn --deny
206
+ ```
207
+
208
+ `deny` 命中即拒且**优先于** `allow` 与联系人集合;同一个 AID 不能同时写在两边(校验期报错)。
209
+ **内置保留字不接受 rules**(`ping`/`list`/`describe`/`schema`/`skill`),写这类键直接报错。
210
+
211
+ ## 六、改完怎么生效
212
+
213
+ **没有自动热重载**(没有 `fs.watch`):改 `pack.json` 或脚本后必须显式重载,否则无声无息地
214
+ 还是旧行为,日志里也看不出异常。
215
+
216
+ ```bash
217
+ # 改了包内容(services/ 下不能直接改,改工作区源目录后重装)
218
+ ec services pack remove hello --aid "$SELF"
219
+ ec services pack add hello --from <工作区>/packs/hello --aid "$SELF"
220
+
221
+ # 只确认状态
222
+ ec services reload --aid "$SELF" # 全量重扫,不接受包名
223
+ ```
224
+
225
+ `pack add` / `pack remove` 内部已经 reload,**不需要**再单独 `reload`。
226
+
227
+ ## 七、常驻形态(`mode: "resident"`):默认别用
228
+
229
+ 一次性 spawn 每次约 80ms 是 node 自己的启动开销。常驻形态让一个进程服务多次调用,稳态降到
230
+ IPC 往返量级。但代价是:
231
+
232
+ - **进程有状态、内存全局共享**:一个调用的脏数据会被下一个调用看见。
233
+ - **不能扩容**,不能跨宿主迁移。
234
+ - 脚本必须按**另一套契约**写:先发 `{t:'ready'}`、每行带原样 `callId`、上下文从帧里读、
235
+ 日志一律走 stderr、**没有退出码**。
236
+ - **正文在 `service.data`**(一次性契约是 `message.data`)——照抄旧脚本会静默拿到 `undefined`。
237
+ - 粒度是「包 + 脚本」:同包不同脚本各一个进程,同脚本共享。临时文件用 `callDir`(每调用一个),
238
+ 缓存用 `workDir`(进程级,不要清空)。帧字段与超时参数见 `$KITS_DOCS/evolcore/services.md` 指向的 `usage.md` §八·五。
239
+ - `host.enabled` 不是 `true` 时(`ec services host enable` 打开,daemonOwner + fullaccess)
240
+ **降级为每次调用起一个进程**:结果一样,没有稳态收益,`doctor` 会给 warn。
241
+
242
+ 有内存累积、需要并行、或者脚本是现成的一次性写法,就留在默认形态。
243
+
244
+ ## 八、排查
245
+
246
+ ```bash
247
+ ec services status # 包状态:active / skipped / invalid / disabled
248
+ ec services types # 本机可接的全部 services.*
249
+ ec services doctor <包名> # requires、保留字遮蔽、脚本、路径、ACL
250
+ ec services ledger <包名> --tail 20 # 生命周期台账
251
+ ec services tail <包名> # 消息日志(含 handled 的 exit / cmd / ms / outcome)
252
+ ec services repair-acl # 历史包的 NTFS ACL 收口(幂等,仅 Windows)
253
+ ```
254
+
255
+ | 症状 | 先看 |
256
+ |---|---|
257
+ | 包不生效 | `status` 里是不是 `skipped`;`requires` 与本机名片对不对(`ec aid agentmd get <自己>`) |
258
+ | 对端调不通 | 你的 `exttype`;`services-config.json` 的 `enabled` 总闸 |
259
+ | 脚本没跑 | `listen.type` 与对端发的字符串是否**完全一致**(含大小写);`filter` 是不是筛掉了 |
260
+ | 脚本跑了但失败 | `logs/` 里 `handled` 的 `exit`、`cmd`、`outcome` |
261
+ | 收不到回复 | `reply.allowed` 是不是 `false`(缺省就是) |
262
+ | `RATE_LIMITED` | 超限,看 `retry_after` |
263
+ | `SCRIPT_OUTPUT_LIMIT` | 输出超过 1 MiB,进程被杀(不是截断) |
264
+ | `logs/` 里有 `sandbox_absent` | 沙箱降级成无沙箱执行了,脚本能读到本不该读的文件 |
265
+
266
+ ## 九、不要做的事
267
+
268
+ 1. **不要在脚本里自己发回复**——输出 `outcome` 让 daemon 发,否则话题、加密态、
269
+ `request_id` 都会错。
270
+ 2. **不要用 `services` 承载不能重复的操作却不做幂等**。daemon 按 `(from, request_id)`
271
+ 只去重 15 秒,更晚的重试会重新执行;真正的幂等键要由脚本按业务字段保证。
272
+ 3. **不要在一个包里给同一个 `type` 写两条 `listen`**。同包重复直接判 invalid。
273
+ 4. **不要在两个包里写同一个 `type`**。两个包都会 invalid,谁先跑没有确定答案。
274
+ 5. **不要把 `exttype` 设成保留字还指望能接**。`exttype=list` 时 `services.list` 被内置抢走,
275
+ 但 `services.list.create` 仍路由到你的包(保留字只占两段形式)。
276
+ 6. **不要指望服务调用带话题**。它不是聊天,没有 `threadId`。
277
+ 7. **不要在 `services/` 目录里直接写文件**。L 类路径,走 `pack add`。
@@ -144,7 +144,7 @@ ec trigger create --event 'task:error' \
144
144
  5. 不直接读 `trigger.json`、`scripts/*`、`data/`、`AIDs/` 这类受保护路径——沙箱按 H 类拦截,
145
145
  脚本会直接启动失败。
146
146
  6. 提示词超过 4096 字符用 `--prompt-file`,不要硬塞。
147
- 7. 群聊里不要用 `--mention` 去 @ 人做提醒——`ec group send` 和 trigger 提示词不共享参数;
147
+ 7. 群聊里不要用 `--mention` 去 @ 人做提醒——`ecmsg send` 和 trigger 提示词不共享参数;
148
148
  要在群里点名,写进目标会话的提示词里,或让 target-session 在群里自己 @。
149
149
 
150
150
  ## 九、排查手册