evolcore 0.0.42 → 0.0.43-test.1

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 (189) hide show
  1. package/CHANGELOG.md +35 -0
  2. package/bin/ec-safe-output.js +4 -1
  3. package/dist/ability/application-service.js +882 -0
  4. package/dist/ability/authorization.js +70 -0
  5. package/dist/ability/command-contract.js +105 -0
  6. package/dist/ability/daemon.js +137 -0
  7. package/dist/ability/development.js +450 -0
  8. package/dist/ability/environment.js +75 -0
  9. package/dist/ability/interop-v1.js +547 -0
  10. package/dist/ability/management.js +79 -0
  11. package/dist/ability/package.js +264 -0
  12. package/dist/ability/provider.js +73 -0
  13. package/dist/ability/publication.js +107 -0
  14. package/dist/ability/resources.js +106 -0
  15. package/dist/ability/runtime.js +212 -0
  16. package/dist/ability/secrets.js +47 -0
  17. package/dist/ability/store.js +112 -0
  18. package/dist/ability/toolchain.js +69 -0
  19. package/dist/ability/types.js +14 -0
  20. package/dist/ability/versions.js +32 -0
  21. package/dist/agents/baseagent.js +2 -2
  22. package/dist/agents/claude-runner.js +4 -0
  23. package/dist/agents/codex-runner.js +81 -17
  24. package/dist/agents/ecagent-plugin-lazy.js +41 -0
  25. package/dist/agents/ecagent-runner.js +18 -11
  26. package/dist/aun/ability-device-routing.js +12 -1
  27. package/dist/aun/aid/agentmd.js +2 -2
  28. package/dist/aun/aid/client.js +1 -1
  29. package/dist/aun/aid/identity.js +45 -0
  30. package/dist/aun/aid/index.js +1 -0
  31. package/dist/aun/aid/managed-operation.js +73 -2
  32. package/dist/channels/aun.js +64 -18
  33. package/dist/channels/builtin-plugins.js +14 -0
  34. package/dist/channels/dingtalk.js +78 -26
  35. package/dist/channels/feishu.js +89 -14
  36. package/dist/channels/qqbot.js +84 -19
  37. package/dist/channels/wechat.js +77 -19
  38. package/dist/channels/wecom.js +67 -22
  39. package/dist/cli/ability-command.js +92 -0
  40. package/dist/cli/aun-commands.js +124 -85
  41. package/dist/cli/daemon-commands.js +37 -85
  42. package/dist/cli/index.js +14 -0
  43. package/dist/cli/init.js +11 -13
  44. package/dist/cli/managed-command-guard.js +6 -0
  45. package/dist/cli/model.js +101 -104
  46. package/dist/cli/provider-command.js +6 -4
  47. package/dist/cli/restart-monitor.js +52 -11
  48. package/dist/cli/upgrade-command.js +102 -0
  49. package/dist/cli/version.js +1 -1
  50. package/dist/config/access-policy.js +4 -2
  51. package/dist/config/builtin-roles.js +1 -0
  52. package/dist/config/config-field-policy.js +4 -0
  53. package/dist/config/config-manager.js +7 -0
  54. package/dist/config/provider-ipc-service.js +10 -0
  55. package/dist/config/providers-config.js +12 -3
  56. package/dist/config/providers-management.js +45 -9
  57. package/dist/config/schema-migration.js +40 -22
  58. package/dist/contracts/ecweb-service-protocol.js +2 -1
  59. package/dist/core/agent-runtime.js +2 -1
  60. package/dist/core/auth/agent-delegation.js +21 -5
  61. package/dist/core/auth/auth-gateway.js +31 -9
  62. package/dist/core/auth/authorization-audit.js +52 -4
  63. package/dist/core/auth/delegation-authorization.js +140 -4
  64. package/dist/core/auth/operation-authorizer.js +114 -13
  65. package/dist/core/auth/operation-catalog.js +118 -4
  66. package/dist/core/baseagent-loader.js +14 -1
  67. package/dist/core/channel-loader.js +47 -9
  68. package/dist/core/channel-runtime.js +1 -1
  69. package/dist/core/command/agent-storage-menu.js +1 -1
  70. package/dist/core/command/cli-intent-parser.js +26 -13
  71. package/dist/core/command/command-handler.js +232 -76
  72. package/dist/core/command/connect-menu.js +10 -4
  73. package/dist/core/command/daemon-diagnostics.js +3 -3
  74. package/dist/core/command/data-root-resolver.js +2 -3
  75. package/dist/core/command/menu-catalog.js +10 -3
  76. package/dist/core/command/menu-handler.js +321 -46
  77. package/dist/core/command/menu-protocol.js +53 -7
  78. package/dist/core/command/pa-workspace-calendar.js +1 -2
  79. package/dist/core/command/pa-workspace-items.js +486 -0
  80. package/dist/core/command/pa-workspace-store.js +10 -1
  81. package/dist/core/command/slash-gate.js +2 -2
  82. package/dist/core/command/slash-handler.js +67 -25
  83. package/dist/core/contact-bind-registry.js +27 -0
  84. package/dist/core/daemon-control.js +3 -3
  85. package/dist/core/daemon-lifecycle.js +2 -1
  86. package/dist/core/event-bus.js +9 -2
  87. package/dist/core/handoff/ipc-registration.js +1 -0
  88. package/dist/core/host-snapshot.js +1 -2
  89. package/dist/core/initialization/service.js +32 -11
  90. package/dist/core/ipc-registration.js +18 -5
  91. package/dist/core/memory/consolidation-context.js +2 -2
  92. package/dist/core/message/aun-request-registry.js +99 -18
  93. package/dist/core/message/im-renderer.js +16 -11
  94. package/dist/core/message/message-admission.js +25 -20
  95. package/dist/core/message/message-bridge.js +21 -47
  96. package/dist/core/message/message-queue.js +3 -0
  97. package/dist/core/message/response-engine.js +7 -5
  98. package/dist/core/model/catalog-service.js +1 -1
  99. package/dist/core/permission/ec-command-parser.js +41 -9
  100. package/dist/core/permission/permission-result.js +1 -0
  101. package/dist/core/permission/protected-paths.js +25 -14
  102. package/dist/core/permission/tool-policy.js +108 -107
  103. package/dist/core/plugin-lifecycle.js +133 -0
  104. package/dist/core/runner-reload-transaction.js +4 -1
  105. package/dist/core/system-session/memory.js +16 -3
  106. package/dist/core/task/task-activity-store.js +50 -0
  107. package/dist/core/task/task-image-resources.js +140 -0
  108. package/dist/core/thread/ipc-operation.js +1 -1
  109. package/dist/core/thread/thread-service.js +0 -1
  110. package/dist/directory/canonical-digest.js +5 -3
  111. package/dist/directory/owner-directory-admission.js +22 -2
  112. package/dist/directory/owner-directory-cache.js +394 -60
  113. package/dist/directory/owner-directory-markdown.js +29 -2
  114. package/dist/directory/owner-directory-scope.js +35 -16
  115. package/dist/ecweb/basic-settings-service.js +4 -1
  116. package/dist/ecweb/pairing.js +41 -0
  117. package/dist/ecweb/providers-service.js +8 -1
  118. package/dist/{utils/ecweb-utils.js → ecweb/runtime/launch.js} +3 -27
  119. package/dist/ecweb/runtime/lifecycle.js +184 -0
  120. package/dist/{utils/ecweb-supervisor.js → ecweb/runtime/supervisor.js} +32 -27
  121. package/dist/index.js +34 -25
  122. package/dist/ipc.js +124 -7
  123. package/dist/response-system/engines/v1/proactive-flow.js +1 -1
  124. package/dist/trigger/authorization.js +2 -2
  125. package/dist/utils/atomic-write.js +24 -0
  126. package/dist/utils/avatar-upload.js +3 -1
  127. package/dist/utils/cross-platform.js +31 -2
  128. package/dist/utils/host-info.js +36 -0
  129. package/dist/utils/instance-registry.js +38 -11
  130. package/dist/utils/logger.js +9 -0
  131. package/dist/utils/{process-tree-stats.js → process-tree.js} +29 -0
  132. package/dist/utils/tool-summary.js +9 -1
  133. package/dist/utils/upgrade-jobs.js +96 -15
  134. package/dist/utils/windows-autostart.js +1 -1
  135. package/ecagent/README.md +19 -0
  136. package/ecagent/dist/harness/agent-harness.js +9 -0
  137. package/ecagent/dist/harness/env/nodejs.js +71 -11
  138. package/ecagent/dist/harness/env/windows-shell.d.ts +7 -0
  139. package/ecagent/dist/harness/env/windows-shell.js +132 -0
  140. package/kits/docs/aun/ABILITY_CALLING.md +38 -9
  141. package/kits/docs/evolcore/INDEX.md +5 -1
  142. package/kits/docs/evolcore/ability.md +181 -0
  143. package/kits/docs/evolcore/aid.md +20 -0
  144. package/kits/docs/evolcore/config.md +10 -6
  145. package/kits/docs/evolcore/menu-protocol.md +40 -1
  146. package/kits/docs/evolcore/provider.md +2 -2
  147. package/kits/docs/evolcore/tool-authorization.md +270 -0
  148. package/kits/runtime/ability-job.ps1 +41 -0
  149. package/kits/runtime/ability-runner.mjs +67 -0
  150. package/kits/runtime/ability-secret.ps1 +59 -0
  151. package/kits/runtime/ability-templates/go/main.go +59 -0
  152. package/kits/runtime/ability-templates/java/Json.java +67 -0
  153. package/kits/runtime/ability-templates/java/Runner.java +42 -0
  154. package/kits/runtime/ability-templates/python/runner.py +48 -0
  155. package/kits/runtime/ability-templates/rust/json.rs +87 -0
  156. package/kits/runtime/ability-templates/rust/runner.rs +35 -0
  157. package/kits/schemas/_meta.json +12 -1
  158. package/kits/schemas/ability-plugin.schema.1.json +107 -0
  159. package/kits/schemas/ability-project.schema.1.json +31 -0
  160. package/kits/schemas/agent-config.schema.16.json +20 -0
  161. package/kits/schemas/agent-config.schema.17.json +20 -0
  162. package/kits/schemas/agent-config.schema.18.json +917 -0
  163. package/kits/skills/.switches.json +4 -0
  164. package/kits/skills/aid-ability/SKILL.md +5 -4
  165. package/kits/skills/ec-ability/SKILL.md +67 -0
  166. package/kits/skills/ec-ability/references/contract-checklist.md +37 -0
  167. package/kits/skills/ec-ability/references/development.md +104 -0
  168. package/kits/skills/ec-ability/references/management.md +117 -0
  169. package/kits/skills/ec-ability/references/recovery.md +27 -0
  170. package/kits/skills/ec-ability/references/runtime-protocol.md +109 -0
  171. package/kits/skills/ec-ability/references/workflows.md +15 -0
  172. package/kits/skills/ec-service-proxy/SKILL.md +12 -0
  173. package/kits/skills/personal-assistant/SKILL.md +240 -6
  174. package/kits/skills/personal-assistant/references/02-bootstrap.md +78 -4
  175. package/kits/skills/personal-assistant/scripts/clean.mjs +397 -0
  176. package/kits/skills/personal-assistant/scripts/init.mjs +113 -25
  177. package/kits/skills/personal-assistant/scripts/lock.mjs +189 -0
  178. package/kits/skills/personal-assistant/scripts/migrate.mjs +35 -10
  179. package/kits/skills/personal-assistant/scripts/verify.mjs +2 -1
  180. package/kits/skills/personal-assistant/templates/persona-section.md +54 -0
  181. package/kits/skills/personal-assistant/triggers/ingest-daily.json +1 -1
  182. package/kits/templates/memory-consolidation/notes.md +1 -1
  183. package/kits/templates/system-fragments/channel.md +2 -1
  184. package/kits/templates/system-fragments/commands.md +1 -0
  185. package/package.json +5 -3
  186. package/dist/core/command/data-root-error.js +0 -10
  187. package/dist/utils/machine-info.js +0 -46
  188. package/dist/utils/process-tree-worker.js +0 -31
  189. package/dist/utils/windows-output.js +0 -36
@@ -29,6 +29,8 @@ license: MIT
29
29
  | "升级工作区" / "同步到新版本" | 先体检,再按迁移修正 | §五 |
30
30
  | "生成日报/周报" | 直接产出报告 | §六 |
31
31
  | "记一下这个" | 当场落地一条原料 | §七 |
32
+ | "清空工作区" / "重来一遍" | 连触发器一起清干净 | §十一 |
33
+ | "锁定工作区" / "定稿了" | 单向锁定,之后谁都不能动 | §十二 |
32
34
 
33
35
  **初始化之前必须先体检**。已有工作区时,初始化等于修复,不是推倒重来。
34
36
 
@@ -51,18 +53,148 @@ license: MIT
51
53
 
52
54
  ## 三、初始化
53
55
 
54
- 调用:
56
+ ### 3.1 工作区放哪(先定路径,再建)
57
+
58
+ **默认落在当前工作目录下的 `PersonalAssistant/`**,即 `$CURRENT_PROJECT/PersonalAssistant`。
59
+
60
+ | 情况 | 路径 |
61
+ |---|---|
62
+ | 有 `$CURRENT_PROJECT`(EvolCore 托管会话) | `$CURRENT_PROJECT/PersonalAssistant` |
63
+ | 用户显式指定了路径 | 用用户给的,不要自作主张 |
64
+ | 既没有 `$CURRENT_PROJECT` 也没有用户指定 | **停下来问**,不要自己挑一个"看起来合理"的位置 |
65
+
66
+ **不要选的位置**:
67
+
68
+ - `Documents/`、`Desktop/`、`Downloads/` —— 那是操作系统给人类用的位置,不是这个 Agent 的工作区
69
+ - `$EVOLCORE_HOME/agents/<aid>/` —— 那是运行时数据,升级或重建 Agent 时会被清掉,违背数据主权
70
+ - `$PACKAGE_ROOT` 内任何位置 —— 那是软件本体,升级会覆盖
71
+
72
+ 判据仍是 `01-workspace-spec.md` §1.1:**卸掉 Skill、换掉 EvolCore,数据还能用文本编辑器直接打开。**
73
+
74
+ ### 3.2 调用
75
+
76
+ **整条初始化只有 4 次命令调用**,一次参数给全,不要拆成多轮试探:
55
77
 
56
78
  ```bash
57
- node "<技能目录>/scripts/init.mjs" --workspace "<工作区绝对路径>" --owner "<owner AID>"
79
+ # 1. 体检(先看是不是已经初始化过——见 3.2.1)
80
+ node "<技能目录>/scripts/check.mjs" --workspace "<工作区绝对路径>"
81
+
82
+ # 2. 建结构 + 装触发器(参数一次给全,尤其 --self 和 --with-triggers)
83
+ node "<技能目录>/scripts/init.mjs" --workspace "<工作区绝对路径>" \
84
+ --owner "<owner AID>" --self "<本 Agent AID>" --with-triggers
85
+
86
+ # 3. 落地今天的对话(可选,想让工作区立刻有内容就跑)
87
+ node "<技能目录>/scripts/ingest.mjs" --workspace "<工作区绝对路径>" --self "<本 Agent AID>" --date today
88
+
89
+ # 4. 重建索引
90
+ node "<技能目录>/scripts/index-rebuild.mjs" --workspace "<工作区绝对路径>"
58
91
  ```
59
92
 
60
- 脚本会:检查前置条件 → 建目录 → 写 README/INDEX → 写 `.assistant/state.json` →
61
- 按需安装触发器 → 输出验收清单。
93
+ 然后写 persona.md(§3.3),最后再跑一次 `check.mjs` 验收。**共 6 步。**
94
+
95
+ 脚本会:检查前置条件 → 建目录 → 写 README/INDEX → 装触发器 → 写 `.assistant/state.json`
96
+ (含 `triggers` 清单和 `capabilities` 实测结果)→ 输出验收清单。
97
+
98
+ > `--self` 不能省。触发器 prompt 里要写 `--self` 才能调通 `ingest.mjs`;
99
+ > 没给 `--self` 时触发器全部装不上,脚本会在验收清单里报 `(all) 缺少 --self`。
62
100
 
63
101
  **装完必须报告三件事**:建了什么、装了什么触发器、**哪些能力不可用**(不要隐瞒降级)。
102
+ 能力结果在 `state.json` 的 `capabilities` 里,直接读,不要自己再探测一遍。
103
+
104
+ #### 3.2.1 先体检,别急着建
105
+
106
+ `init.mjs` 是幂等的(已存在的触发器跳过、已有目录不重建),但它**回答不了这个问题**:
107
+ "工作区目录是空的,可触发器早就在了,这是怎么回事?"
108
+
109
+ 初始化之前先跑 `check.mjs`:
110
+
111
+ | 输出 | 含义 | 下一步 |
112
+ |---|---|---|
113
+ | `工作区不存在` / `v0 未初始化` | 全新 | 正常走 §3.2 |
114
+ | `OK:N 项全部符合` | 已初始化过 | **不要重跑 init**,直接进 §3.3 检查 persona.md |
115
+ | `MISSING` | 初始化到一半 | 跑 `init.mjs` 补建 |
116
+ | `DRIFT` | 版本落后 | 走 §五 升级 |
117
+
118
+ > 实测教训:曾跳过体检直接 init,结果 4 个触发器早就存在(比工作区早 20 分钟,
119
+ > 是 Core 的 `pa-workspace init` 建的),脚本报了一屏"已存在",agent 又跑去翻源码
120
+ > 才搞清状况,多花了几十次调用。
121
+
122
+ #### 3.2.2 别读源码
123
+
124
+ 脚本是确定性的,**文档写的就是它的行为**。不要为了"确认脚本怎么跑"去读
125
+ `init.mjs` / `apply.mjs` / `schema.mjs`——要确认用法跑 `--help`,要确认结果看输出。
126
+ 唯一需要读源码的情形是:输出和文档矛盾,需要判断是脚本 bug 还是文档过时。
127
+
128
+ ### 3.3 写回 persona.md(必做,否则等于没装)
129
+
130
+ **这一步不做,初始化就只是建了一堆没人知道的空目录。**
131
+
132
+ 工作区路径只存在 `.assistant/` 和 Core 的导航状态里,两者都**不进上下文**。
133
+ 新会话开场的你是个不知道工作区存在的普通 agent,主人得每次重新交代路径——
134
+ 这违背了"把复杂度锁在技能里"的前提。
135
+
136
+ `persona.md`(`$PERSONAL_DIR/persona.md`)是唯一**保证每轮注入**的位置:ECK manifest 的
137
+ `persona` 段只要求 `chatType ≠ null` 且 `lifecycle = active`,**不依赖任何记忆开关**。
138
+ 相比之下 `memory/MEMORY.md` 虽然默认开启(`memory.enableAgent ?? true`),但可以被关掉;
139
+ 而且 `ec memory note` 写的 `pending/` 要等整理会话跑完才进索引——**中间那段是断的**,
140
+ 不能当唯一入口。
141
+
142
+ **先备份,再重建。不要试图合并。**
143
+
144
+ 合并看起来温柔,实际最容易出错:漏读一段、拼接位置错、编码不对,都会悄悄毁掉原文,
145
+ 而且毁了还不知道。备份 + 重建只有两种结局——**要么成功,要么原样可退**。
146
+
147
+ 用 Read / Write 工具直接操作文件,不走脚本、不用 `ec agent persona --file` 转手临时文件
148
+ (那条路是整体覆盖,天然做不了"先备份")。
149
+
150
+ 三步:
151
+
152
+ 1. **备份老的**:`persona.md` 存在就整份复制到同目录的 `persona.before-personal-assistant.md`。
153
+ **备份已存在时不要覆盖**——最早那份才是真正的原始状态,后面的重复初始化不能拿
154
+ 已经被改过的版本去顶掉它。文件不存在就跳过(原始状态就是"没有",见下面「清理」)。
155
+ 2. **重新创建**:Write 一份新的 `persona.md`,内容按 `templates/persona-section.md` 渲染。
156
+ 备份里有想保留的个人信息,**从备份里抄过来**,不要指望原文件还在。
157
+ 3. **写完复查**:Read 一遍,确认路径、入口清单、触发器列表都在,备份文件也还在。
158
+
159
+ ### 清理(撤销初始化)
160
+
161
+ 初始化必须可逆,否则用户不敢用。撤销时把备份放回去,删掉这次创建的内容:
162
+
163
+ ```bash
164
+ # 有备份:恢复原始状态
165
+ mv persona.before-personal-assistant.md persona.md
166
+
167
+ # 没有备份(原本就不存在):删掉这次创建的
168
+ rm persona.md
169
+ ```
170
+
171
+ **删之前必须先确认备份存在且非空。** 没有备份就直接删,等于把用户的原始人格永久销毁——
172
+ 这一步不可逆,做之前必须跟用户说清楚。
173
+
174
+ **这一节必须写清什么**:
175
+
176
+ 1. **工作区绝对路径**,以及"涉及归档/回顾/报告/任务时先读它的 `INDEX.md`"。
177
+ 2. **目录用途**:`capture/` 原料、`output/reports/` 报告、`output/tasks/` 任务、
178
+ `output/knowledge/` 持久沉淀。
179
+ 3. **"什么时候该进来读"**——不是只写"这里有个工作区"。入口越具体,新会话越会真的去读:
180
+
181
+ | 触发情形 | 动作 |
182
+ |---|---|
183
+ | 「记一下」「归档」 | 落 `capture/`,原文照录 |
184
+ | 「以前说过什么」「上次那个」 | 先搜工作区再回答 |
185
+ | 日报 / 周报 / 月报 | 读对应周期原料再写,带 `source:` |
186
+ | 任务、待办、跟进 | 读 `output/tasks/` |
187
+ | 某人、某组织 | 读 `output/knowledge/profile/` |
188
+
189
+ 4. **持久记忆是什么**:工作区 `output/knowledge/memory/` 改主意不改老条目,旧版本标
190
+ `superseded` 永久保留。这是运行时记忆故意做不到的事。
191
+ 5. **已装触发器清单**,避免下次重复创建。
192
+ 6. **不改人格主体**:新文件里只放本技能需要的内容,不编造性格设定、不写行为守则。
193
+
194
+ `persona.md` 缺失时没有默认人格兜底,这一节就是新会话唯一的入口——**它缺了,整个工作区对外不可见**。
64
195
 
65
- 详细流程见 `references/02-bootstrap.md`。
196
+ 参考成品见 `templates/persona-section.md`(整份 persona 的模板,含备份+重建的用法说明)。
197
+ 详细流程见 `references/02-bootstrap.md` 阶段 4.5。
66
198
 
67
199
  ---
68
200
 
@@ -157,6 +289,19 @@ node "<技能目录>/scripts/check.mjs" --workspace "<路径>" # 3. 复查
157
289
  | `schema/workspace.schema.json` | 目标结构的机器可读定义(`check` 依据) |
158
290
  | `schema/migrations/` | 版本迁移步骤 |
159
291
 
292
+ **脚本速查**(全部用绝对路径调用):
293
+
294
+ | 脚本 | 作用 | 退出码 0 的含义 |
295
+ |---|---|---|
296
+ | `init.mjs` | 建/修复工作区 | 成功(含"已是最新") |
297
+ | `check.mjs` | 只读体检 | 完全一致;`10` = 有缺失可补建 |
298
+ | `migrate.mjs` | 版本迁移 | 成功(含"无需迁移") |
299
+ | `ingest.mjs` | 对话落地 | 成功 |
300
+ | `index-rebuild.mjs` | 重建索引 | 成功 |
301
+ | `verify.mjs` | 完整性校验 | 通过;`10` = 通过但有警告 |
302
+ | `clean.mjs` | 清理(§十一) | 成功;`30` = 已锁定拒绝 |
303
+ | `lock.mjs` | 锁定(§十二) | 成功;`10` = 本来就锁着 |
304
+
160
305
  主会话只读 SKILL.md。需要细节时按上表取用,不要一次全读。
161
306
 
162
307
  ---
@@ -173,4 +318,93 @@ node "<技能目录>/scripts/check.mjs" --workspace "<路径>" # 3. 复查
173
318
  3. 给出替代方案或留占位
174
319
  4. **不要把"留了空目录"说成"已经能落地"**
175
320
 
176
- 完整缺口清单见 `references/03-data-flow-and-gaps.md` §4。
321
+ 完整缺口清单见 `references/03-data-flow-and-gaps.md` §4。
322
+
323
+ ---
324
+
325
+ ## 十一、清理(重建工作区)
326
+
327
+ **只删工作区目录是不够的。** 有三样东西住在工作区外面,删目录不会带走它们:
328
+
329
+ | 残留物 | 在哪 | 留着会怎样 |
330
+ |---|---|---|
331
+ | 4 个 `pa-*` 触发器 | EvolCore 的系统目录 | 每天半夜按时醒来,对着不存在的路径报错 |
332
+ | persona.md 的「## 数据位置」小节 | `$PERSONAL_DIR/persona.md` | 新会话每轮都被告知去读一个已经没了的路径 |
333
+ | Core 的工作区绑定登记 | `agents/<aid>/data/pa-workspace-state.json` | 导航面板还挂着一个不存在的路径 |
334
+
335
+ `clean.mjs` 四样一起清(含工作区目录本身):
336
+
337
+ ```bash
338
+ # 1. 先预览(默认就是预览,不加 --yes 什么都不删)
339
+ node "<技能目录>/scripts/clean.mjs" --workspace "<路径>" --self "<AID>"
340
+
341
+ # 2. 确认后执行
342
+ node "<技能目录>/scripts/clean.mjs" --workspace "<路径>" --self "<AID>" --yes
343
+ ```
344
+
345
+ **清理是不可逆的,所以默认只预览。** 这不是多余的谨慎——工作区里可能有用户几个月的数据。
346
+
347
+ **Core 登记为什么要删文件而不是调命令**:`ec pa-workspace` 只有 `init` / `bind` / `navigation`,
348
+ **没有 `unbind`**。所以脚本直接删 `pa-workspace-state.json`。
349
+
350
+ **删之前必须核对 `rootPath`**:这个文件同时存着 `ownerAid` 和导航条目,
351
+ 只有 `rootPath` 精确等于当前要清理的工作区时才删。指向别的工作区就跳过,
352
+ 不会误删其他 Agent 的登记。
353
+
354
+ **已锁定的工作区拒绝清理**,没有绕过开关(见 §十二)。
355
+
356
+ ---
357
+
358
+ ## 十二、锁定(定稿后禁止任何自动化改动)
359
+
360
+ 工作区确认无误、数据已经定稿时锁定:
361
+
362
+ ```bash
363
+ node "<技能目录>/scripts/lock.mjs" --workspace "<路径>" --reason "定稿,2026 年度档案" --yes
364
+ node "<技能目录>/scripts/lock.mjs" --workspace "<路径>" --show # 查状态
365
+ ```
366
+
367
+ **锁定是单向的,没有 unlock。**
368
+
369
+ 这不是偷懒,是设计:锁的语义是"这份数据定稿了,别再让任何自动化碰它"。
370
+ 留一个 unlock,就等于留了一个能被误触发的后门,锁本身就失去了意义。
371
+ 真要用它,只能由人手动删掉 `<工作区>/.assistant/LOCK`——**这一步必须绕过本工具,是刻意的摩擦**。
372
+
373
+ 锁定后:
374
+
375
+ | 脚本 | 行为 |
376
+ |---|---|
377
+ | `init.mjs` | 🔒 拒绝(退出码 30) |
378
+ | `migrate.mjs` | 🔒 拒绝(退出码 30) |
379
+ | `clean.mjs` | 🔒 拒绝(退出码 30) |
380
+ | `check.mjs` / `verify.mjs` / `search.mjs` | 正常(只读,不改东西) |
381
+ | `ingest.mjs` / `index-rebuild.mjs` | 正常(往 capture 追加、重建索引,不改结构) |
382
+
383
+ **锁定前先备份。** 锁上之后工具层面取不回来,只剩人手动操作。
384
+
385
+ ### 为什么 LOCK 是独立文件,不写进 state.json
386
+
387
+ `state.json` 是运行时状态,会被 `init` / `migrate` 重写。锁必须独立存在,
388
+ 且**任何一个脚本都不该有"顺手改它"的路径**——写进 state.json 就等于
389
+ 每次跑 init 都可能把锁冲掉。
390
+
391
+ ---
392
+
393
+ ## 十三、测试阶段怎么反复来
394
+
395
+ 创建 → 验证 → 清理 → 再创建,这个循环是支持的:
396
+
397
+ ```bash
398
+ # 1. 建
399
+ node "<技能目录>/scripts/init.mjs" --workspace "<路径>" --owner "<AID>" --self "<AID>" --with-triggers
400
+ # 2. 验
401
+ node "<技能目录>/scripts/check.mjs" --workspace "<路径>"
402
+ # 3. 清(连触发器一起)
403
+ node "<技能目录>/scripts/clean.mjs" --workspace "<路径>" --self "<AID>" --yes
404
+ # 4. 回到第 1 步
405
+ ```
406
+
407
+ 每一轮都应该是干净的:没有残留触发器、没有残留 persona 小节、没有残留 Core 登记、没有半截目录。
408
+ 如果第 2 步发现上一轮的残留,那是 bug,不是正常现象。
409
+
410
+ **测试阶段不要锁定。** 锁上了就只能手动删 LOCK 文件,会打断这个循环。
@@ -51,7 +51,30 @@ description: 个人助理工作区。当用户要求"初始化个人助理/个
51
51
 
52
52
  ## 3. 初始化流程
53
53
 
54
- ### 阶段 0:前置检查(只读,不改任何东西)
54
+ ### 阶段 0:定路径(必须先做,且不可自行发挥)
55
+
56
+ **默认路径:`$CURRENT_PROJECT/PersonalAssistant`**,也就是当前工作目录下的 `PersonalAssistant/`。
57
+
58
+ | 情况 | 动作 |
59
+ |---|---|
60
+ | 有 `$CURRENT_PROJECT` | 用 `$CURRENT_PROJECT/PersonalAssistant` |
61
+ | 用户显式指定 | 用用户给的 |
62
+ | 两者都没有 | **停下来问用户**,不要自己挑位置 |
63
+
64
+ **明确禁止**的路径:
65
+
66
+ | 位置 | 为什么不行 |
67
+ |---|---|
68
+ | `Documents/` `Desktop/` `Downloads/` | 操作系统给人类用的目录,不是 Agent 的工作区 |
69
+ | `$EVOLCORE_HOME/agents/<aid>/` | 运行时数据,Agent 重建即丢失,违背数据主权 |
70
+ | `$PACKAGE_ROOT` 内任意位置 | 软件本体,升级会覆盖 |
71
+
72
+ 判据见 `01-workspace-spec.md` §1.1:**卸掉 Skill、换掉 EvolCore,数据还能用文本编辑器打开。**
73
+
74
+ > 历史教训:曾因 `--workspace` 未给出具体值而自行选择 `Documents/PersonalAssistant`,
75
+ > 事后需要 `mv` + 重新 `bind` 才能纠正。初始化路径一旦定错,后面每天都在错的地方跑。
76
+
77
+ ### 阶段 0.5:前置检查(只读,不改任何东西)
55
78
 
56
79
  | 检查项 | 不通过时 |
57
80
  |---|---|
@@ -127,15 +150,52 @@ ec trigger create --exec trigger-session --file triggers/ingest-daily.json --ena
127
150
 
128
151
  装失败的单独报告,不因为一个失败就整体回滚——助理有 80% 功能可用,胜过一次都不跑。
129
152
 
153
+ ### 阶段 4.5:备份并重建 persona.md
154
+
155
+ **这一步由模型直接用 Read / Write 编辑文件完成,不调脚本。**
156
+
157
+ | 步骤 | 动作 |
158
+ |---|---|
159
+ | 1. 备份 | `persona.md` 存在 → 整份复制到 `persona.before-personal-assistant.md`。<br>**备份已存在不覆盖**,最早那份才是真正的原始状态。不存在 → 跳过 |
160
+ | 2. 重建 | Write 新的 `persona.md`,按 `templates/persona-section.md` 渲染。<br>备份里有要保留的信息,从备份里抄 |
161
+ | 3. 复查 | Read 确认路径、入口清单、触发器都在;备份文件也在 |
162
+
163
+ **为什么是备份+重建,而不是读旧的→合并→写新的**:合并看起来温柔,实际最容易出错——
164
+ 漏读一段、拼接位置错、编码不对,都会悄悄毁掉原文,而且毁了不知道。
165
+ 备份 + 重建只有两种结局:**要么成功,要么原样可退**。
166
+
167
+ **为什么不用 `ec agent persona --text/--file`**:那两个参数是**整体覆盖**,
168
+ 必须先自己拼好全文再传,天然做不了"先备份再重建";而且中间还要落一个临时文件。
169
+ owner 会话里直接读写 persona 文件是被允许的。
170
+
171
+ **为什么必须做**:工作区路径只存在 `.assistant/state.json` 和 Core 的导航状态里,
172
+ 两者都**不进上下文**。`persona.md` 是唯一保证每轮注入的位置(manifest 的 `persona` 段
173
+ 只要求 `chatType ≠ null` + `lifecycle = active`)。不写这一步,新会话根本不知道工作区存在。
174
+
175
+ #### 撤销初始化
176
+
177
+ ```bash
178
+ # 有备份:恢复原始状态
179
+ mv persona.before-personal-assistant.md persona.md
180
+
181
+ # 没有备份(原本就不存在):删掉这次创建的
182
+ rm persona.md
183
+ ```
184
+
185
+ **删之前必须确认备份存在且非空**。没有备份就删 = 永久销毁用户原始人格,不可逆,
186
+ 做之前必须跟用户讲清楚。
187
+
130
188
  ### 阶段 5:验收
131
189
 
132
190
  输出一份清单,让用户一眼知道"成了没有":
133
191
 
134
192
  ```
135
- ✅ 工作区已创建:/evolcore-projects/xxx
193
+ ✅ 工作区已创建:<CURRENT_PROJECT>/PersonalAssistant
136
194
  ✅ 目录:4 个根项 + 29 个子目录
137
195
  ✅ README / INDEX 已生成
138
196
  ✅ state.json 已写入(技能版本 0.1.0)
197
+ ✅ persona.md 已重建(含「数据位置」一节,新会话据此发现工作区)
198
+ 原文件已备份为 persona.before-personal-assistant.md
139
199
  ✅ 触发器:5 个已启用
140
200
  ├─ ingest-daily 下次 23:50
141
201
  ├─ ingest-on-idle 事件驱动
@@ -151,7 +211,13 @@ ec trigger create --exec trigger-session --file triggers/ingest-daily.json --ena
151
211
  2. `INDEX.md` 可被 `scripts/index-rebuild` 重建且内容一致
152
212
  3. `state.json` 可读,版本号正确
153
213
  4. 至少 `ingest-daily` 和 `report-daily` 两个触发器处于 enabled
154
- 5. 已报告的能力缺口,用户知情
214
+ 5. **`persona.md` 里有「数据位置」一节**:工作区路径 + "什么时候该进来读"的入口清单
215
+ 6. **原 persona 已备份**(原本存在时):`persona.before-personal-assistant.md` 内容与原文一致,
216
+ 且撤销命令能原样恢复
217
+ 7. 已报告的能力缺口,用户知情
218
+
219
+ > 第 5 条是硬性的。工作区路径只落在 `.assistant/` 和 Core 导航状态里,两者都不进上下文;
220
+ > 不进 `persona.md`,新会话就是不知道有这么个地方,等于没装。详见 SKILL.md §3.3。
155
221
 
156
222
  ---
157
223
 
@@ -167,9 +233,14 @@ ec trigger create --exec trigger-session --file triggers/ingest-daily.json --ena
167
233
  | `state.json` 缺失 | 重建,标记 `recovered: true` |
168
234
  | 技能版本升级 | 保留全部数据,只更新 `state.json` 和触发器定义 |
169
235
  | 触发器丢失或被禁用 | 重新安装,不重复创建(按 `name` 去重) |
236
+ | `persona.md` 里没有工作区入口 | 按阶段 4.5 重新备份+重建(**备份已存在则不覆盖**) |
170
237
 
171
238
  **永远不删用户数据。** 修复模式只做加法。
172
239
 
240
+ `persona.md` 是唯一例外:它是**重建**而非追加,所以必须有备份兜底。
241
+ 重复初始化时 `persona.before-personal-assistant.md` 已存在就保持原样——
242
+ 那份是最早的原始状态,不能被后来改过的版本顶掉。
243
+
173
244
  ### 4.2 版本迁移
174
245
 
175
246
  `workspace_version` 变更时,按 `migrations/` 下的脚本逐步迁移,每一步可回滚。迁移前自动把 `state.json` 和目录结构快照到 `.assistant/logs/migrate-<ts>.json`。
@@ -191,7 +262,10 @@ EvolCore 检测到新对端是"个人"类型时,自动创建工作区。
191
262
  留给未来的接口约定:
192
263
 
193
264
  - `scripts/init --auto --owner <aid>` 必须支持静默执行(无交互)
194
- - 退出码语义固定:`0` 成功、`10` 已存在无需操作、`20` 部分成功、`30` 前置条件不满足
265
+ - 退出码语义固定:`0` 成功(**含"已存在、无需操作"**)、`20` 部分成功、`30` 前置条件不满足
266
+ - 不设 `10` 表示"无需操作":shell 的 `&&`、CI、触发器调度一律把非 0 当失败,
267
+ "✅ 已是最新"却返回 10,会让正常的幂等重跑被判成出错。
268
+ 要区分"做了事"和"没事可做",读 `--json` 输出里的 `noop` 字段,不要靠退出码。
195
269
 
196
270
  这样将来 EvolCore 直接调用即可,不需要改脚本。
197
271