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