evolcore 0.0.43-test.2 → 0.0.43-test.3

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 (110) hide show
  1. package/CHANGELOG.md +8 -1
  2. package/dist/agents/ecagent-runner.js +13 -6
  3. package/dist/aun/aid/agentmd.js +21 -1
  4. package/dist/aun/msg/p2p.js +4 -2
  5. package/dist/channels/aun.js +79 -48
  6. package/dist/channels/daemon.js +4 -0
  7. package/dist/cli/agent-create.js +3 -5
  8. package/dist/cli/aun-commands.js +17 -19
  9. package/dist/cli/directory.js +101 -56
  10. package/dist/cli/index.js +1 -1
  11. package/dist/cli/peer.js +2 -1
  12. package/dist/cli/task-context.js +3 -1
  13. package/dist/config/access-policy.js +0 -1
  14. package/dist/config/builtin-role-templates.js +2 -2
  15. package/dist/config/builtin-roles.js +2 -1
  16. package/dist/config/config-field-policy.js +5 -0
  17. package/dist/config/config-manager.js +25 -10
  18. package/dist/config/peer-role-resolver.js +23 -1
  19. package/dist/config/role-schema.js +26 -2
  20. package/dist/config/role-service.js +9 -4
  21. package/dist/config/role-store.js +30 -8
  22. package/dist/core/auth/auth-gateway.js +14 -4
  23. package/dist/core/auth/operation-authorizer.js +17 -0
  24. package/dist/core/auth/operation-catalog.js +12 -2
  25. package/dist/core/channel-runtime.js +5 -0
  26. package/dist/core/command/agent-control.js +1 -1
  27. package/dist/core/command/agentmd-menu-request.js +50 -0
  28. package/dist/core/command/agentmd-menu.js +156 -0
  29. package/dist/core/command/command-handler.js +39 -3
  30. package/dist/core/command/menu-catalog.js +13 -0
  31. package/dist/core/command/menu-handler.js +59 -9
  32. package/dist/core/command/menu-protocol.js +8 -0
  33. package/dist/core/command/role-menu.js +23 -9
  34. package/dist/core/command/slash-handler.js +48 -21
  35. package/dist/core/daemon-lifecycle.js +9 -1
  36. package/dist/core/evolagent.js +5 -4
  37. package/dist/core/lifecycle-notice.js +185 -0
  38. package/dist/core/message/aun-ipc-sender.js +30 -24
  39. package/dist/core/message/contact-admission.js +1 -19
  40. package/dist/core/message/im-renderer.js +64 -28
  41. package/dist/core/message/message-admission.js +15 -65
  42. package/dist/core/message/message-bridge.js +18 -5
  43. package/dist/core/message/message-utils.js +9 -0
  44. package/dist/core/message/peer-mode.js +16 -8
  45. package/dist/core/message/response-engine.js +56 -35
  46. package/dist/core/ownership/owner-resolver.js +72 -34
  47. package/dist/core/permission/ec-command-parser.js +24 -10
  48. package/dist/core/relation/pa-team.js +127 -0
  49. package/dist/core/role/runtime-policy.js +4 -3
  50. package/dist/core/thread/thread-service.js +6 -4
  51. package/dist/directory/owner-directory-admission.js +0 -3
  52. package/dist/directory/owner-directory-cache.js +197 -15
  53. package/dist/directory/owner-directory-markdown.js +44 -21
  54. package/dist/directory/owner-directory-policy.js +1 -1
  55. package/dist/directory/owner-directory-query-operation.js +219 -97
  56. package/dist/directory/owner-directory-request-operation.js +76 -0
  57. package/dist/directory/owner-directory-scope.js +35 -4
  58. package/dist/directory/owner-directory-search.js +76 -23
  59. package/dist/directory/owner-directory-store.js +5 -38
  60. package/dist/directory/owner-directory-text.js +60 -0
  61. package/dist/eck/kit-renderer.js +6 -3
  62. package/dist/eck/message-renderer.js +2 -5
  63. package/dist/ecweb/message-context-service.js +4 -0
  64. package/dist/index.js +11 -0
  65. package/dist/paths.js +4 -2
  66. package/dist/product.js +1 -0
  67. package/dist/response-system/engines/v1/index.js +2 -4
  68. package/dist/response-system/modes/single-session/index.js +1 -1
  69. package/dist/trigger/scheduler.js +8 -3
  70. package/dist/utils/error-utils.js +7 -5
  71. package/ecagent/README.md +18 -0
  72. package/ecagent/dist/harness/agent-harness.d.ts +2 -0
  73. package/ecagent/dist/harness/agent-harness.js +24 -8
  74. package/ecagent/dist/harness/compaction/compaction.js +3 -0
  75. package/ecagent/dist/harness/types.d.ts +1 -0
  76. package/kits/docs/channels/aun.md +1 -1
  77. package/kits/docs/context-assembly.md +1 -1
  78. package/kits/docs/evolcore/INDEX.md +4 -1
  79. package/kits/docs/evolcore/directory.md +125 -35
  80. package/kits/docs/evolcore/ecweb-lifecycle.md +26 -0
  81. package/kits/docs/evolcore/file-navigation.md +265 -0
  82. package/kits/docs/evolcore/msg.md +1 -0
  83. package/kits/docs/evolcore/peer.md +2 -1
  84. package/kits/docs/evolcore/response.md +2 -2
  85. package/kits/docs/evolcore/task.md +2 -0
  86. package/kits/docs/evolcore/tool-authorization.md +1 -1
  87. package/kits/docs/identity/ROLE_DETAIL.md +2 -0
  88. package/kits/eck_manifest.json +7 -3
  89. package/kits/eck_manifest.memory.json +26 -1
  90. package/kits/schemas/_meta.json +16 -3
  91. package/kits/schemas/agent-config.schema.20.json +925 -0
  92. package/kits/schemas/relation-config.schema.13.json +289 -0
  93. package/kits/schemas/role-config.schema.3.json +1038 -0
  94. package/kits/schemas/role-registry.schema.1.json +3 -2
  95. package/kits/templates/soul/00-GUIDE.md +20 -42
  96. package/kits/templates/system-fragments/channel.md +2 -2
  97. package/kits/templates/system-fragments/commands.md +1 -1
  98. package/kits/templates/system-fragments/directory-contacts.md +1 -1
  99. package/kits/templates/system-fragments/personal-assistant.md +2 -17
  100. package/kits/templates/system-fragments/reply.md +7 -0
  101. package/kits/templates/system-fragments/session.md +6 -2
  102. package/package.json +2 -2
  103. package/dist/eck/paactive-context.js +0 -45
  104. package/dist/response-system/engines/v1/paactive-flow.js +0 -18
  105. package/kits/eck_manifest.paactive.json +0 -528
  106. package/kits/eck_message_manifest.paactive.json +0 -233
  107. package/kits/templates/message-fragments/paactive/item.md +0 -3
  108. package/kits/templates/system-fragments/paactive/channel.md +0 -25
  109. package/kits/templates/system-fragments/paactive/reply.md +0 -25
  110. package/kits/templates/system-fragments/paactive/session.md +0 -32
@@ -450,7 +450,7 @@ export function _setDictPath(p) {
450
450
  // - 中文:上下文过长
451
451
  //
452
452
  // ⚠️ 新增措辞统一往这里加,不要再在各模块本地复制正则。
453
- export const CONTEXT_TOO_LONG_PATTERN = /prompt is too long|input is too long|context too long|context limit|context_length_exceeded|context_window_exceeded|context window limit|reached its context window|exceed(?:s|ed)? the context window|maximum context length|上下文过长/i;
453
+ export const CONTEXT_TOO_LONG_PATTERN = /prompt is too long|input is too long|context (?:is )?too (?:long|large)|context limit|context_length_exceeded|context_window_exceeded|context window limit|reached its context window|exceed(?:s|ed)? the context window|maximum context length|上下文(?:过长|过大)/i;
454
454
  /** 判断一段文本是否为「上下文过长」类错误。空文本返回 false。 */
455
455
  export function isContextTooLongText(text) {
456
456
  if (!text)
@@ -501,6 +501,9 @@ export function classifyError(error) {
501
501
  if (error?.code === CLAUDE_CODE_STARTUP_FAILED) {
502
502
  return ErrorType.CLAUDE_CODE_STARTUP_FAILED;
503
503
  }
504
+ if (msg.includes('context_compact_failed') || isContextTooLongText(getErrorRawText(error))) {
505
+ return ErrorType.CONTEXT_TOO_LONG;
506
+ }
504
507
  // 字典优先 — 命中则直接返回
505
508
  const rule = matchErrorRule(msg);
506
509
  if (rule) {
@@ -513,9 +516,6 @@ export function classifyError(error) {
513
516
  return ErrorType.UNKNOWN;
514
517
  }
515
518
  // 内置兜底规则(结构性、稳定的错误模式)
516
- if (msg.includes('context_compact_failed') || isContextTooLongText(msg)) {
517
- return ErrorType.CONTEXT_TOO_LONG;
518
- }
519
519
  if (msg.includes('invalid_model') || msg.includes('model_not_found')
520
520
  || msg.includes('no such model') || msg.includes('unknown model')
521
521
  || /api error: 404\b/.test(msg)) {
@@ -559,6 +559,8 @@ export function isRetryableError(error) {
559
559
  const lower = msg.toLowerCase();
560
560
  if (lower.includes('invalid jsonl session file') || lower.includes('invalid session file'))
561
561
  return false;
562
+ if (lower.includes('context_compact_failed') || isContextTooLongText(getErrorRawText(error)))
563
+ return false;
562
564
  // The idle watchdog emits this exact terminal error when a runner stops
563
565
  // producing events. The provider session remains resumable, so the task
564
566
  // recovery trigger must be allowed to continue the original session.
@@ -679,7 +681,7 @@ export function getErrorMessage(error, terminalReason, includeEmoji = true) {
679
681
  }
680
682
  // 字典优先 — 命中且有自定义消息则直接返回
681
683
  const rule = matchErrorRule(msg.toLowerCase());
682
- if (rule?.message)
684
+ if (rule?.message && (!isContextTooLongText(msg) || rule.type === ErrorType.CONTEXT_TOO_LONG))
683
685
  return rule.message;
684
686
  // 内置兜底规则(结构性错误)
685
687
  if (msg.includes('CONTEXT_COMPACT_FAILED') || isContextTooLongText(msg)) {
package/ecagent/README.md CHANGED
@@ -60,6 +60,24 @@ pending, interruption terminates all processes in its job. Long-running managed
60
60
  services should use EvolCore's service manager rather than rely on an open Bash
61
61
  tool call. The supervisor fails closed if job assignment is unavailable.
62
62
 
63
+ ## Automatic context compaction
64
+
65
+ `AgentHarness` accepts an optional `autoCompactWindow` token threshold. When set
66
+ to a positive number, the harness checks context usage before each model request,
67
+ including requests between tool batches. It summarizes older history, persists a
68
+ compaction entry, and rebuilds the context without restarting the task or replaying
69
+ tools. The public `compact()` method still requires an idle harness.
70
+
71
+ The threshold is opt-in for standalone callers. EvolCore supplies the same
72
+ window-aware threshold used by its Claude adapter: the smaller of 650,000 tokens
73
+ and the model window minus a reserve of up to 10,000 tokens (5% for smaller
74
+ windows). EvolCore's task-start check and context-overflow recovery remain in place.
75
+
76
+ Automatic summaries inherit the active run's cancellation signal. Context estimates
77
+ ignore usage recorded before the latest compaction; retained recent messages are
78
+ estimated until a new provider response reports usage for the compacted context.
79
+ This is threshold-based summarization, not continuous history pruning.
80
+
63
81
  ## Build from source
64
82
 
65
83
  ```bash
@@ -13,6 +13,7 @@ export declare class AgentHarness<TSkill extends Skill = Skill, TPromptTemplate
13
13
  private thinkingLevel;
14
14
  private systemPrompt;
15
15
  private streamOptions;
16
+ private readonly autoCompactWindow?;
16
17
  private resources;
17
18
  private tools;
18
19
  private activeToolNames;
@@ -63,6 +64,7 @@ export declare class AgentHarness<TSkill extends Skill = Skill, TPromptTemplate
63
64
  tokensBefore: number;
64
65
  details?: unknown;
65
66
  }>;
67
+ private performCompaction;
66
68
  navigateTree(targetId: string, options?: {
67
69
  summarize?: boolean;
68
70
  customInstructions?: string;
@@ -1,6 +1,6 @@
1
1
  import { runAgentLoop } from "../agent-loop.js";
2
2
  import { collectEntriesForBranchSummary, generateBranchSummary } from "./compaction/branch-summarization.js";
3
- import { compact, DEFAULT_COMPACTION_SETTINGS, prepareCompaction } from "./compaction/compaction.js";
3
+ import { compact, DEFAULT_COMPACTION_SETTINGS, estimateContextTokens, prepareCompaction } from "./compaction/compaction.js";
4
4
  import { convertToLlm } from "./messages.js";
5
5
  import { formatPromptTemplateInvocation } from "./prompt-templates.js";
6
6
  import { formatSkillInvocation } from "./skills.js";
@@ -124,6 +124,7 @@ export class AgentHarness {
124
124
  this.models = options.models;
125
125
  this.resources = options.resources ?? {};
126
126
  this.streamOptions = cloneStreamOptions(options.streamOptions);
127
+ this.autoCompactWindow = options.autoCompactWindow;
127
128
  this.systemPrompt = options.systemPrompt;
128
129
  this.validateUniqueNames((options.tools ?? []).map((tool) => tool.name), "Duplicate tool name(s)");
129
130
  for (const tool of options.tools ?? []) {
@@ -325,9 +326,18 @@ export class AgentHarness {
325
326
  model: turnState.model,
326
327
  reasoning: turnState.thinkingLevel === "off" ? undefined : turnState.thinkingLevel,
327
328
  convertToLlm,
328
- transformContext: async (messages) => {
329
- const result = await this.emitHook({ type: "context", messages: [...messages] });
330
- return result?.messages ?? messages;
329
+ transformContext: async (messages, signal) => {
330
+ let currentMessages = messages;
331
+ signal?.throwIfAborted();
332
+ if (this.autoCompactWindow && this.autoCompactWindow > 0
333
+ && estimateContextTokens(messages).tokens >= this.autoCompactWindow) {
334
+ await this.flushPendingSessionWrites();
335
+ await this.performCompaction(undefined, signal);
336
+ signal?.throwIfAborted();
337
+ currentMessages = (await this.session.buildContext()).messages;
338
+ }
339
+ const result = await this.emitHook({ type: "context", messages: [...currentMessages] }, signal);
340
+ return result?.messages ?? currentMessages;
331
341
  },
332
342
  beforeToolCall: async ({ toolCall, args }, signal) => {
333
343
  const result = await this.emitHook({
@@ -614,8 +624,13 @@ export class AgentHarness {
614
624
  async compact(customInstructions) {
615
625
  if (this.phase !== "idle")
616
626
  throw new AgentHarnessError("busy", "compact() requires idle harness");
627
+ return this.performCompaction(customInstructions);
628
+ }
629
+ async performCompaction(customInstructions, signal) {
630
+ const previousPhase = this.phase;
617
631
  this.phase = "compaction";
618
632
  try {
633
+ signal?.throwIfAborted();
619
634
  const model = this.model;
620
635
  if (!model)
621
636
  throw new AgentHarnessError("invalid_state", "No model set for compaction");
@@ -631,16 +646,17 @@ export class AgentHarness {
631
646
  preparation,
632
647
  branchEntries,
633
648
  customInstructions,
634
- signal: new AbortController().signal,
635
- });
649
+ signal: signal ?? new AbortController().signal,
650
+ }, signal);
636
651
  if (hookResult?.cancel)
637
652
  throw new AgentHarnessError("compaction", "Compaction cancelled");
638
653
  const provided = hookResult?.compaction;
639
654
  const compactResult = provided
640
655
  ? { ok: true, value: provided }
641
- : await compact(preparation, this.models, model, customInstructions, undefined, this.thinkingLevel);
656
+ : await compact(preparation, this.models, model, customInstructions, signal, this.thinkingLevel);
642
657
  if (!compactResult.ok)
643
658
  throw compactResult.error;
659
+ signal?.throwIfAborted();
644
660
  const result = compactResult.value;
645
661
  const entryId = await this.session.appendCompaction(result.summary, result.firstKeptEntryId, result.tokensBefore, result.details, provided !== undefined);
646
662
  const entry = await this.session.getEntry(entryId);
@@ -653,7 +669,7 @@ export class AgentHarness {
653
669
  throw normalizeHarnessError(error, "compaction");
654
670
  }
655
671
  finally {
656
- this.phase = "idle";
672
+ this.phase = previousPhase;
657
673
  }
658
674
  }
659
675
  async navigateTree(targetId, options) {
@@ -87,7 +87,10 @@ export function getLastAssistantUsage(entries) {
87
87
  return undefined;
88
88
  }
89
89
  function getLastAssistantUsageInfo(messages) {
90
+ const summary = messages.find((message) => message.role === "compactionSummary");
90
91
  for (let i = messages.length - 1; i >= 0; i--) {
92
+ if (summary && messages[i].timestamp <= summary.timestamp)
93
+ continue;
91
94
  const usage = getAssistantUsage(messages[i]);
92
95
  if (usage)
93
96
  return { usage, index: i };
@@ -610,6 +610,7 @@ export interface AgentHarnessOptions<TSkill extends Skill = Skill, TPromptTempla
610
610
  }) => string | Promise<string>);
611
611
  /** Curated stream/provider request options. Snapshotted at turn start. */
612
612
  streamOptions?: AgentHarnessStreamOptions;
613
+ autoCompactWindow?: number;
613
614
  model: Model<any>;
614
615
  thinkingLevel?: ThinkingLevel;
615
616
  activeToolNames?: string[];
@@ -57,7 +57,7 @@ AUN keystore seed 由 EvolCore 使用固定应用值管理,不再提供配置
57
57
  - **身份与信任**:每条入站消息携带发送者 AID,经四级 X.509 证书链(Root CA → Registry CA → Issuer CA → Agent)验签。
58
58
  - **agent.md 缓存**:对端名片 `https://<aid>/agent.md` 由 **AUN SDK 自动拉取并缓存**(`AgentMdManager`,带 ETag/TTL,默认 1 天内不重复探测)。缓存落在 **`$EVOLCORE_HOME/AIDs/<aid>/`**,每个 AID 两个文件:`agent.md`(带签名正文)+ `agentmd.json`(元数据:etag/last_modified/checked_at/verify_status)。本端与对端的 agent.md 都缓存于此。
59
59
  - 关系层另存一份**派生**的精简身份 `relations/<peerKey>/peer-identity.json`(type/isAgent/name),由 evolcore 从 agent.md 提取,不是 agent.md 本体。
60
- - **E2EE 加密**:可选端到端加密,回复默认跟随对端消息加密状态(密文回密文,明文回明文);keystore seed 由 EvolCore 固定管理。
60
+ - **E2EE 加密**:可选端到端加密,回复默认跟随对端消息加密状态(密文回密文,明文回明文);主动发起默认明文,只有显式 `--encrypt` 或 `aun.defaultEncrypt: true` 才加密;keystore seed 由 EvolCore 固定管理。
61
61
  - **断线重连**:SDK 内置退避策略自动重连。实时连接状态用 `ec watch aid` 查看(`ec aid` 是身份/证书管理,不显示连接状态)。
62
62
  - **群 ID 格式**:使用 `{base}.{issuer}`,如 `ontology.agentid.cn` 或 `g-12345.agentid.cn`。EvolCore 默认创建 `g-` 加五位数字(10000–99999)的名称,issuer 以群服务返回为准。群命令支持 base 简写;不再支持或转换 `group.{issuer}/{base}`,也不支持 `base@issuer`。`g-` 是名称的一部分,不应剥离,也不能仅凭群 AID 的格式判断主体类型。
63
63
  - **群 @ 处理策略**:`mention_mode=disabled|mention-only` 是群级配置,只决定哪些群消息进入 Agent LLM 上下文,不影响 AUN 协议层投递;被过滤消息仍应本地存档。
@@ -49,7 +49,7 @@ evolcore 收到消息 → 构造一份 **vars**(运行时变量,见下)→
49
49
  渲染时按 `session.sessionType`(缺省 `'main'`)依次查:`sessionManifests` 覆盖 → 内置映射 → `eck_manifest.json`(`resolveSessionManifest`)。bootstrapping 阶段固定用 `eck_manifest.json`。
50
50
  **每个 manifest 文件各自两级合并**(`$KITS/<file>` + `$ECK/<file>`),互不干扰。
51
51
 
52
- `chatMode=paactive` 是主会话的模式专用例外,不是新的 sessionType。active AUN 人类 owner/admin 私聊(含话题)使用独立的 `eck_manifest.paactive.json` 与 `eck_message_manifest.paactive.json`,由 `src/eck/paactive-context.ts` 分别构建 system/message vars;不继承 `sessionManifests.main`,也不注入 proactive 专属门禁变量。Bootstrap 与系统会话仍优先走原 manifest 选择路径。PA 的必要 manifest/片段缺失时报告上下文构建错误,不回退到另一模式提示词。
52
+ `chatMode=paactive` 是私聊文本展示分支,不是新的 `sessionType` 或独立上下文体系。active AUN 人类 Owner 私聊(含话题)继续使用按现有生命周期、sessionType 和 `sessionManifests` 选择的 system/message manifest,并复用基础 vars;`chatMode` 保持 `paactive`。派生变量 `activePush=true` 表示正式回复使用托管发送,供共用模板复用发送说明。Proactive 工具门禁变量仅在 proactive 任务注入。群聊固定 proactive;interactive 和 paactive 仅适用于私聊。
53
53
 
54
54
  ## section 字段
55
55
 
@@ -28,6 +28,8 @@
28
28
  | `ec logs` | 查看日志(`--level` `--module` `--raw` `--no-color`) | 日志/查看日志 |
29
29
  | `ec diagnose` | 诊断启动环境 | 诊断/环境诊断 |
30
30
 
31
+ ECWeb 托管重启、端口占用与升级失败处理见 `ecweb-lifecycle.md`。
32
+
31
33
  Windows 上 Codex 托管任务出现 `helper_sandbox_lock_failed`、`SetNamedSecurityInfoW ... 5`、`unelevated ... cannot enforce deny-read` 或 daemon 管道 `EPERM` 时,参见 `codex-windows-sandbox.md`。
32
34
 
33
35
  ## 对外通信 / 网络类(连 AUN,以 AID 为发送者)
@@ -45,7 +47,7 @@ Windows 上 Codex 托管任务出现 `helper_sandbox_lock_failed`、`SetNamedSec
45
47
  | `ec storage` | 文件存储底层调试入口 | storage 调试/旧命令/底层上传下载 | 任意有渠道场景 | `storage.md` |
46
48
  | `ec agent` | EvolAgent 生命周期与主机信息 | 创建/启停/热重载/改配置/查主机信息 | 管理操作按目标与角色鉴权 | `agent.md`;创建流程用 `ec-agent-create` 技能,Bootstrap 参考见 `agent-create.md` |
47
49
  | `ec peer` | 对端身份与本地拉黑 | 查已登记对端、拉黑/解除拉黑 | 拉黑为 Agent 自身行为;添加联系人与审批归 Owner | `peer.md` |
48
- | `ec directory` | Owner 名录查询与本地备注 | 联系人/通讯录/名录/找人的 AID/这个人是谁/内外联系人/拉黑名单/记备注 | 有 Owner 名录授权;`remark set/rm` 仅 Owner 的个人助理 | `directory.md` |
50
+ | `ec directory` | Owner 名录查询、入录申请与本地备注 | 联系人/通讯录/名录/找人的 AID/申请添加联系人/这个人是谁/内外联系人/拉黑名单/记备注 | 查询需 Owner 名录授权;申请通过 `request` 发给本端 Owner | `directory.md` |
49
51
  | `ec rpc` | 底层 AUN RPC(逃生通道) | 直接调协议方法 | 仅宿主终端;托管会话仅可查看帮助 | `rpc.md` |
50
52
  | `ec menu-client` | 远程 Daemon Menu 请求 | 远程诊断/远程 daemon 操作/daemon 日志/监控/原始配置/跨主机 | 运维主机或具备 `ec.menu.request` 权限的托管 Agent | `menu-client.md` |
51
53
 
@@ -82,6 +84,7 @@ Windows 上 Codex 托管任务出现 `helper_sandbox_lock_failed`、`SetNamedSec
82
84
  | `ec task` | 恢复暂停或异常中断的会话任务 | 任务恢复/异常中断/继续任务/resume | `task.md` |
83
85
  | `ec skill` | EC 技能管理(新建/安装/删除/启用/禁用/校验/查路径) | 创建技能/新建 skill/安装技能/装个 skill/删除技能/禁用技能/启用技能/看看有哪些技能/技能为什么没生效 | `ec-capabilities.md` |
84
86
  | `ec pa-workspace` | 在 Owner 的 AUN 私聊中查看和维护 PA 工作区入口导航 | 个人助理工作区/工作区入口调整/产物入口/报告入口/任务入口/隐藏入口/改名入口/排序入口 | `pa-workspace.md` |
87
+ | `ec pa-workspace` | 入口导航文件的位置、格式、schema 与安全改法;含跨 Agent 入口 | 导航格式/入口格式/加个入口/产物给用户看/加个报告入口/入口指向别的助理/file-navigation/导航文件在哪 | `file-navigation.md` |
85
88
 
86
89
  ## 开发者工具(非 agent 会话能力)
87
90
 
@@ -1,4 +1,4 @@
1
- # ec directory — Owner 名录查询与本地备注
1
+ # ec directory — Owner 名录查询、入录申请与本地备注
2
2
 
3
3
  `ec directory` 读的是 **Owner 下发的名录副本** `<agent>/directory/contacts.json`(只读),
4
4
  以及本地补充的**备注文件** `<agent>/directory/remarks/<aid>.md`。
@@ -6,56 +6,115 @@
6
6
  触发词:联系人/通讯录/名录/找人的 AID/这个人是谁/内外联系人/拉黑名单/记备注。
7
7
 
8
8
  它不是联系人管理入口:谁能联系这个 Agent、名录里有哪些人,由 Owner 在 Evol App 里决定,
9
- Agent 侧只能查询,不能增删名录条目。
9
+ Agent 侧可以查询或向 Owner 发送入录申请,不能直接增删名录条目。
10
10
 
11
- ## 命令
11
+ ## 命令面
12
+
13
+ 命令与 `ec skill` 对齐:**`list` 列举/过滤,`info` 看单条详情**。
14
+
15
+ ```bash
16
+ ec directory list [<关键词>...] [--filter '<kw1,kw2>']... [--type <type>] [--scope internal|external|all] [--owner <aid|unbound>] [--limit <n>] [--page <n>] [--format json]
17
+ ec directory info <contact-aid|名字> [--limit <n>] [--format json]
18
+ ec directory refresh [--format json]
19
+ ec directory blocked [--format json]
20
+ ec directory request <target-aid> [--note <申请说明>] [--format json]
21
+ ```
22
+
23
+ 旧名仍可用:`find <关键词>` 等价于 `list <关键词>`,`show <AID|名字>` 等价于 `info`。
24
+
25
+ `--self` 缺省时:托管会话取**当前任务所属 Agent**(来自委托凭据,等于当前会话的
26
+ `selfAid`),非托管会话取 `EVOLCORE_SELF_AID`。显式传 `--self` 时必须等于当前任务
27
+ 所属 Agent,否则报 `SCOPE_MISMATCH`。
28
+
29
+ > 托管 runner 不注入 `EVOLCORE_SELF_AID`,所以以前在托管会话里省略 `--self` 会直接
30
+ > 报 `--self <agent-aid> is required`。现在与 `ec peer` / `ec role` 一致,由 daemon
31
+ > 用委托凭据补齐。
32
+
33
+ ## 申请加入 Owner 名录
34
+
35
+ 当发送因目标不在本端 Owner 名录中被拒绝时,执行:
12
36
 
13
37
  ```bash
14
- ec directory find <query> --self <agent-aid> [--type <type>] [--scope internal|external|all] [--owner <aid|unbound>] [--limit <n>] [--format json]
15
- ec directory show <contact-aid|名字> --self <agent-aid> [--limit <n>] [--format json]
16
- ec directory list --self <agent-aid> [--type <type>] [--scope internal|external|all] [--owner <aid|unbound>] [--limit <n>] [--format json]
17
- ec directory refresh --self <agent-aid> [--format json]
18
- ec directory blocked --self <agent-aid> [--format json]
38
+ ec directory request evolapplwj.agentid.cn --note "三藏希望了解项目接下来的工作重点"
19
39
  ```
20
40
 
21
- `--self` 缺省取 `EVOLCORE_SELF_AID`;托管会话里必须等于当前任务所属 Agent。
41
+ `request` 自动确定本端 Agent 与其 Owner,向 Owner 发送一条**加密加好友申请**(app-v1
42
+ `friend.invite.v1`),列明本端 Agent、目标 AID 和申请说明(最多 500 字符)。Owner 需要在
43
+ Evol App 中处理该申请,并把目标加入联系人名录、允许本 Agent 访问对应的联系人范围。
44
+ 申请不会给目标发送消息,也不会修改本地名录、准入开关或自动重发原消息。
45
+
46
+ 成功返回 `action: request`、`targetAid`、`status: sent` 和 `message_id`,
47
+ 仅表示申请消息已发送,**不表示 Owner 已同意或目标已入录**。Owner 处理后执行
48
+ `ec directory refresh`,同步名录后再重试原发送命令。
49
+
50
+ ## list — 列举与关键词过滤
51
+
52
+ 不给关键词时列举名录;给关键词时按 **AID、名字、备注、描述、exttype** 做子串匹配,
53
+ 不区分大小写,比较前统一归一(全角转半角、去零宽字符、折叠空格)。
54
+
55
+ 两种写法:
56
+
57
+ - `--filter '<kw1,kw2>'`:与 `ec skill list --filter` 同语义,**组内逗号分隔为 OR,
58
+ 多个 `--filter` 之间为 AND**;
59
+ - 位置参数(`list 张三 采购`):保留旧 `find` 的语义,多个词**同时命中**(AND)。
22
60
 
23
- ## 查询
61
+ 其它过滤:`--type`、`--scope internal|external|all`(默认 `all`)、
62
+ `--owner <aid|unbound>`(按条目归属过滤,`unbound` 只列没有 `owner_aid` 的条目)。
24
63
 
25
- ### find
64
+ **分页**:默认每页 20 条,上限 100。`--limit` / `--page` 可调;JSON 结果带
65
+ `page` / `limit` / `total` / `hasMore`。
26
66
 
27
- 按 AID、名字、备注、描述匹配。查询串按空白切成多个词,**要求全部命中**(AND),
28
- 按命中字段打分排序(精确 AID/名字 > 前缀 > 备注 > 域段 > 包含 > 描述)。
67
+ 输出(文本与 JSON 一致)包含完整条目字段:
29
68
 
30
- - 默认 `--scope all`(含外部条目),`--limit 5`,上限 50。
31
- - `--owner <aid>` 按条目归属过滤;`--owner unbound` 只列没有 `owner_aid` 的条目。
32
- - 本地备注优先于远端字段参与匹配——备注是这个 Agent 自己记的判断。
33
- - 本地没有命中时会触发一次有界同步再查一遍("刚更新还没拉下来",不是"没有这个人")。
69
+ ```
70
+ 名字 | AID | type | exttype | 备注名 | 描述 | Owner: <owner_aid|(无)> | 归属: owned|unknown
71
+ ```
72
+
73
+ - `ownershipStatus`(归属:)是 `contacts.json` 里的双边归属核验结果;
74
+ `ownershipVerified` 为 `true` 表示 `owned`。
75
+ - 本地备注正文(`localRemark`)**不在 list 展示**;要看正文用 `ec directory info <AID>`。
76
+ - **Owner 与个人助理**也属于可查询条目(它们在快照顶层,不在 `entries` 里)。
77
+ - 归属未核实、没有 `owner_aid`、`type` 不合规的条目**同样会被 list 出来**,
78
+ 并带上 `ownerAid` / `ownershipStatus`,方便判断为什么它们不在注入的“内部联系人”里。
79
+
80
+ 不命中时会触发一次有界同步再查一遍(“刚更新还没拉下来”,不是“没有这个人”)。
34
81
 
35
- ### show
82
+ ## info — 单条详情
36
83
 
37
- 接受 **AID 或名字**两种形式:
84
+ 接受 **AID 或名字**两种形式,Owner 与个人助理同样可查。AID 大小写不敏感,也接受
85
+ `@aid` 前缀。
38
86
 
39
87
  - 合法 AID → 精确匹配,返回一条。
40
- - 其它值 → 按名字匹配**显示名、远端备注名、本地备注名**(精确等于,不模糊),
41
- 同名多条时全部返回。
88
+ - 其它值 → 按名字匹配**显示名、远端备注名、本地备注名**,分两级:
89
+ 1. **精确**:比较前先归一(全角转半角、去零宽字符、折叠空格、忽略大小写),
90
+ 并忽略名字结尾括号里的称呼(`李文江(研发)` 与 `李文江` 视为同名);
91
+ 2. 精确没命中才放宽为**名字/称呼包含**查询串(只在名字与称呼里找,**不匹配描述**,
92
+ 避免把「李文江的助理」当成李文江本人)。这一级结果带 `matchKind: "fuzzy"`,
93
+ 需要调用方自己再确认。
94
+ - 两级都没命中时报 `NOT_FOUND`,错误信息里附最多 3 条**相近条目**(按编辑距离,
95
+ 用于纠正错字/称呼差异)。`--format json` 时同样给出结构化错误。
42
96
  - 默认最多 20 条,`--limit` 可改;超出时结果带 `truncated` 字段。
43
97
 
44
- 返回完整记录(描述不截断)。远端字段与本地备注**并列返回,互不覆盖**:
98
+ 返回完整记录(描述与本地备注正文都不截断),并带 `ownerAid` /
99
+ `ownershipStatus` / `ownershipVerified`。远端字段与本地备注**并列返回,互不覆盖**:
45
100
  `description` 始终是远端描述,本地正文放在 `localRemark`;
46
101
  `remark` 优先取本地称呼(没有则回落远端备注名),`ownerRemark` 保留远端备注名。
47
102
 
48
- ### list
103
+ ### 三种“看详情”不要混
49
104
 
50
- 按范围列条目,默认 `--scope internal`。输出「名字 | AID | 类型 | 备注名」。
105
+ | 想看什么 | 命令 |
106
+ |---|---|
107
+ | 名录档案(type/exttype/描述/本地备注正文/归属状态) | `ec directory info <AID>` |
108
+ | 名片正文(agent.md 全文,下载 + 验签,任意合法 AID) | `ec aid agentmd get <AID>` |
109
+ | 本地身份诊断(私钥/证书/agent.md 状态;托管会话仅限 self) | `ec aid show <AID>` |
51
110
 
52
- ### refresh
111
+ ## refresh
53
112
 
54
- 强制拉一次最新名录并落地,不看摘要门控(区别于 `find` 未命中时的顺带同步)。
113
+ 强制拉一次最新名录并落地,不看摘要门控(区别于 `list` 不命中时的顺带同步)。
55
114
 
56
115
  **需要该 Agent 的 channel 在线**:没有活连接时返回 `REFRESH_UNAVAILABLE`,不会静默假装成功。
57
116
 
58
- ### blocked
117
+ ## blocked
59
118
 
60
119
  列出被拉黑的主体,合并两个来源:
61
120
 
@@ -69,6 +128,29 @@ ec directory blocked --self <agent-aid> [--format json]
69
128
 
70
129
  > 本地拉黑用 `ec peer block/unblock`(见 `peer.md`),`ec directory blocked` 只做查看。
71
130
 
131
+ ## 归属核验(ownership_status)
132
+
133
+ `contacts.json` 每条带 `ownership_status`(`owned` / `unknown`)与
134
+ `ownership_checked_at_ms`。它是 Owner 侧对“这条主体是否确实归属于本 Owner”的
135
+ **双边核验结果**。
136
+
137
+ 判定口径(渲染、准入、查询三处一致):
138
+
139
+ ```
140
+ agent 类型:内部联系人 = owner_aid == owner.aid AND ownership_status == 'owned'
141
+ human 等非 agent 类型:内部联系人 = owner_aid == owner.aid
142
+ ```
143
+
144
+ - 门禁只作用于 **`type=agent`**:会自称“我是某某的 Agent”并据此索取内部待遇的
145
+ 是 Agent;人类联系人由 Owner 在名录里直接维护,`owner_aid` 本身就是明确指派;
146
+ - agent 的 `unknown`、字段缺失、`owner_aid` 指向别人或没有 `owner_aid`,都**不是内部**,
147
+ 不参与 `allowInternalContacts` 的默认放行;
148
+ - Owner / 个人助理两个顶层身份块单独处理:它们已与 `authorization.json` 的授权
149
+ Owner 做过一致性校验,按已核验对待。
150
+
151
+ 没有这条门禁时,一个 Agent 只要在名录里把 `owner_aid` 写成我们的 Owner,
152
+ 就能拿到内部联系人的默认放行——这是必须堵住的口子。
153
+
72
154
  ## 备注
73
155
 
74
156
  备注描述的是「**这个 Agent 自己怎么看这个人**」,和 Owner 发布的远端条目不是一回事。
@@ -94,7 +176,7 @@ updated_at: <unix 秒>
94
176
  - 文件名必须与 frontmatter 的 `aid` 一致,否则整条作废——防止备注挂到别人头上。
95
177
  - `remark` 可以写**多个称呼**,用中英文逗号、顿号或空格分隔:`remark: 蒋总, 老蒋, 蒋先生`。
96
178
  名字后括号里放第一个,其余与 Owner 的备注名一起进备注名列(`蒋先福(蒋总) | … | 老蒋、蒋先生`)。
97
- - `find` 和 `show` 对**每一个**称呼都能命中;同名重复的自动去重。
179
+ - `list` 与 `info` 对**每一个**称呼都能命中;同名重复的自动去重。
98
180
  - 正文**不覆盖**描述,而是**追加**在远端描述之后、带 `备注:` 前缀单独占一列。
99
181
  远端描述是对方或 Owner 写的身份,本地正文是 PA 自己记的「什么事该找他」,
100
182
  替换掉等于把原始事实删了;前缀让模型能分清哪段是谁写的。
@@ -107,31 +189,39 @@ updated_at: <unix 秒>
107
189
  | 形态 | 内容 | 用于 |
108
190
  |---|---|---|
109
191
  | `full` | 名字 \| AID \| 类型 \| 备注名 \| 描述 \| 备注:… | 内部联系人、白名单联系人 |
110
- | `brief` | 名字 \| 备注名 | 外部 Agent/人类、加入的群、无 Owner 的 Agent、类型未知 |
192
+ | `brief` | 名字 \| 备注名 | 外部 Agent/人类、加入的群、归属未核实 |
193
+
194
+ 「内部联系人」组只收 `exttype` 以 `pa.` 打头的本 Owner 条目;其余内部主体不注入。
111
195
 
112
196
  `brief` 组里**有本地备注的条目会逐条升级为 `full`**——记了备注就等于把这个人从"只有名字"
113
- 变成"可以直接用",不用再 find + show 两次。
197
+ 变成"可以直接用",不用再 list + info 两次。
114
198
 
115
- `show` 返回里 `description` 始终是远端描述,本地正文单独放在 `localRemark`,两者并存;
116
- `remarkSource` 标明 `remark` 字段来自 `local` 还是 `remote`。
199
+ **归属未核实组**:`type=agent` 且 `ownership_status !== 'owned'`、没有 `owner_aid`、
200
+ 或 `type` 不在协议 8 种之内(`agent`/`human`/`group`/`service`/`device`/`org`/`custom`/`host`)
201
+ 的条目,只注入**名字**(有本地备注时也带称呼),不展示 AID、类型与描述,并明确提示
202
+ “不要当作内部联系人、不要主动联系”。完整字段用 `ec directory list` 现查。
117
203
 
118
204
  ## 输出与错误
119
205
 
120
- `--format json` 输出结构化结果。常见失败码:
206
+ `--format json` 输出结构化结果,**失败时也是 JSON**:`{ ok: false, code, error }`
207
+ (此前失败只打印 `❌ …` 文本,调用方拿不到错误码)。常见失败码:
121
208
 
122
209
  | code | 含义 |
123
210
  |---|---|
124
211
  | `NOT_AUTHORIZED` | 这个 Agent 没有可用的名录授权(`authorization.json` 缺失或与身份不符) |
125
212
  | `NO_SNAPSHOT` | 已授权但本地还没有快照(从未成功拉取过) |
126
- | `NOT_FOUND` | `show` 找不到目标 |
213
+ | `NOT_FOUND` | `info` 找不到目标 |
127
214
  | `REFRESH_UNAVAILABLE` | `refresh` 时没有可用的 channel 连接 |
128
215
  | `AGENT_NOT_FOUND` | `--self` 指向的 Agent 不存在 |
216
+ | `OWNER_NOT_FOUND` | `request` 无法确定本端 Owner,未发送申请 |
217
+ | `OWNER_REQUEST_FAILED` | 申请消息发送失败或未取得发送回执 |
129
218
 
130
219
  ## 权限边界
131
220
 
132
221
  | 操作 | 授权目录项 | 说明 |
133
222
  |---|---|---|
134
- | `find` / `show` / `list` / `refresh` / `blocked` | `ec.directory.query` | 只读 |
223
+ | `list` / `info` / `refresh` / `blocked`(含旧名 `find` / `show`) | `ec.directory.query` | 只读 |
224
+ | `request` | `ec.directory.request` | 向当前 Agent 的 Owner 发送加密申请;按 Agent Owner + bypass 授权 |
135
225
 
136
226
  托管会话里 CLI 不直接读盘,携带 task delegation token 调 daemon `directory.op`;
137
227
  缺 token、token 伪造或跨会话时失败关闭。显式 `--self` 必须等于当前任务所属 Agent。
@@ -0,0 +1,26 @@
1
+ # ECWeb 生命周期与升级
2
+
3
+ ## 源码归属
4
+
5
+ 宿主侧 ECWeb 集成集中在 `src/ecweb/`:`runtime/supervisor.ts` 负责守护与恢复调度,`runtime/lifecycle.ts` 负责退出确认和重启就绪校验,`runtime/launch.ts` 负责启动入口及版本兼容检查,`pairing.ts` 负责配对 IPC、访问链接和提示文案。通用跨平台进程工具仍留在 `src/utils/`;独立 Web 服务自身代码留在 `ecweb/src/`。
6
+
7
+ ## 重启顺序
8
+
9
+ 托管 ECWeb 的重启由 `restart-monitor` 协调:
10
+
11
+ 1. 停止旧 daemon,并等待其退出。
12
+ 2. 在替换安装包或启动新 daemon 前,核验并停止旧 ECWeb。
13
+ 3. 先发送优雅退出信号,超时后才发送强制退出信号。
14
+ 4. 新 daemon 写入 `ready.signal` 后,还必须通过 ECWeb `/api/health`、`/api/ready` 和实例登记校验。
15
+
16
+ ## 安全边界
17
+
18
+ - 已登记实例核验登记契约、所属 Home、PID 与启动时间;未登记实例还必须核验 ECWeb 启动入口、`--home` 和服务健康身份。
19
+ - 旧版本没有实例登记时,只有端口监听进程的命令行和 `/api/health` 都匹配,才允许回收。
20
+ - PID 被复用时不向新进程发送信号;启动时间不可读取、服务身份不匹配或端口仍被占用时中止重启,不发送不确定的终止信号。
21
+ - 停止后除扫描监听 PID,还实际绑定并释放目标端口,避免系统扫描工具缺失或失败时误判端口空闲。
22
+ - `runtimeMode=external` 或服务禁用时,不由 EvolCore 管理其进程。
23
+
24
+ ## 故障处理
25
+
26
+ ECWeb 停止失败会留下可诊断的实例登记,不替换安装包,也不继续启动重复实例。状态命令会扫描配置端口,即使登记文件丢失,也会报告端口占用和 PID,提示先核实进程归属。