evolcore 0.0.41-test.0 → 0.0.41-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 (177) hide show
  1. package/CHANGELOG.md +49 -0
  2. package/dist/agents/baseagent-availability.js +1 -1
  3. package/dist/agents/baseagent.js +20 -43
  4. package/dist/agents/claude-runner.js +177 -92
  5. package/dist/agents/codex-runner.js +84 -28
  6. package/dist/agents/ecagent-runner.js +1 -1
  7. package/dist/agents/gemini-runner.js +1 -1
  8. package/dist/aun/group/fs-download.js +39 -0
  9. package/dist/aun/group/identity.js +36 -21
  10. package/dist/aun/group/operations.js +5 -0
  11. package/dist/aun/msg/managed-operation.js +68 -7
  12. package/dist/aun/msg/p2p.js +5 -0
  13. package/dist/aun/service-proxy.js +36 -12
  14. package/dist/channels/aun.js +334 -20
  15. package/dist/channels/daemon.js +15 -1
  16. package/dist/cli/aun-commands.js +4 -20
  17. package/dist/cli/daemon-commands.js +678 -697
  18. package/dist/cli/fs-command.js +64 -2
  19. package/dist/cli/index.js +48 -4
  20. package/dist/cli/managed-command-guard.js +4 -0
  21. package/dist/cli/model.js +40 -40
  22. package/dist/cli/proxy-command.js +92 -0
  23. package/dist/cli/role.js +85 -0
  24. package/dist/config/access-policy.js +7 -2
  25. package/dist/config/boot-log.js +38 -1
  26. package/dist/config/config-field-policy.js +5 -32
  27. package/dist/config/config-manager.js +46 -39
  28. package/dist/config/config-operation-service.js +5 -19
  29. package/dist/config/contact-book-store.js +47 -21
  30. package/dist/config/contact-book.js +18 -12
  31. package/dist/config/contact-operation-service.js +3 -4
  32. package/dist/config/contact-request-service.js +11 -0
  33. package/dist/config/daemon-services.js +11 -0
  34. package/dist/config/gateway-config.js +88 -594
  35. package/dist/config/peer-role-resolver.js +13 -11
  36. package/dist/config/providers-config.js +12 -7
  37. package/dist/config/providers-import.js +3 -21
  38. package/dist/config/resolved-config-op.js +3 -0
  39. package/dist/config/role-command-service.js +166 -0
  40. package/dist/config/role-request-service.js +193 -0
  41. package/dist/config/schema-migration.js +686 -25
  42. package/dist/config-store.js +79 -3
  43. package/dist/contracts/ecweb-instance.js +41 -0
  44. package/dist/contracts/ecweb-service-protocol.js +3 -1
  45. package/dist/core/agent-runtime.js +1 -1
  46. package/dist/core/auth/agent-delegation.js +2 -1
  47. package/dist/core/auth/auth-gateway.js +1 -1
  48. package/dist/core/auth/authorization-audit.js +17 -6
  49. package/dist/core/auth/delegation-authorization.js +3 -1
  50. package/dist/core/auth/operation-authorizer.js +15 -0
  51. package/dist/core/auth/operation-catalog.js +31 -6
  52. package/dist/core/command/agent-control.js +3 -7
  53. package/dist/core/command/agent-storage-menu.js +5 -3
  54. package/dist/core/command/cli-intent-parser.js +2 -1
  55. package/dist/core/command/command-handler.js +48 -99
  56. package/dist/core/command/connect-menu.js +11 -3
  57. package/dist/core/command/data-root-resolver.js +5 -4
  58. package/dist/core/command/memory-slash.js +16 -8
  59. package/dist/core/command/menu-catalog.js +5 -6
  60. package/dist/core/command/menu-handler.js +49 -62
  61. package/dist/core/command/role-menu.js +147 -30
  62. package/dist/core/command/slash-handler.js +123 -254
  63. package/dist/core/daemon-control.js +8 -14
  64. package/dist/core/evolagent-registry.js +4 -4
  65. package/dist/core/evolagent.js +2 -2
  66. package/dist/core/inference/text-inference.js +31 -40
  67. package/dist/core/ipc-registration.js +6 -2
  68. package/dist/core/memory/consolidation-context.js +51 -5
  69. package/dist/core/memory/consolidation-ops-records.js +1 -1
  70. package/dist/core/memory/consolidation-trigger.js +189 -189
  71. package/dist/core/memory/consolidation.js +316 -29
  72. package/dist/core/memory/forget-log.js +96 -0
  73. package/dist/core/memory/index-manager.js +27 -5
  74. package/dist/core/memory/memory-admin.js +45 -5
  75. package/dist/core/memory/memory-writer.js +163 -18
  76. package/dist/core/memory/relation-idle-monitor.js +119 -58
  77. package/dist/core/memory/relation-sweep.js +44 -39
  78. package/dist/core/message/aun-ipc-sender.js +8 -2
  79. package/dist/core/message/im-renderer.js +7 -4
  80. package/dist/core/message/message-admission.js +89 -4
  81. package/dist/core/message/message-bridge.js +31 -18
  82. package/dist/core/message/response-engine.js +77 -8
  83. package/dist/core/model/catalog-service.js +4 -2
  84. package/dist/core/model/config-scope.js +24 -64
  85. package/dist/core/model/field-scope.js +1 -1
  86. package/dist/core/model/model-catalog.js +30 -41
  87. package/dist/core/model/model-diagnostics.js +4 -3
  88. package/dist/core/model/model-fallback.js +10 -7
  89. package/dist/core/model/model-permission.js +3 -2
  90. package/dist/core/ownership/owner-resolver.js +23 -21
  91. package/dist/core/permission/ec-command-parser.js +30 -2
  92. package/dist/core/permission/sandbox-runtime.js +18 -1
  93. package/dist/core/permission/tool-policy.js +14 -3
  94. package/dist/core/relation/peer-identity.js +64 -1
  95. package/dist/core/role/runtime-policy.js +72 -13
  96. package/dist/core/session/session-capsule.js +1 -1
  97. package/dist/core/session/session-idle-monitor.js +1 -1
  98. package/dist/core/session/session-manager.js +20 -0
  99. package/dist/core/session/session-renew.js +3 -3
  100. package/dist/core/skill/index-generator.js +15 -5
  101. package/dist/core/system-session/memory.js +6 -1
  102. package/dist/core/thread/thread-service.js +19 -6
  103. package/dist/directory/owner-directory-admission.js +95 -0
  104. package/dist/directory/owner-directory-authorization.js +309 -0
  105. package/dist/directory/owner-directory-cache.js +635 -0
  106. package/dist/eck/kit-renderer.js +2 -2
  107. package/dist/ecweb/basic-settings-service.js +33 -40
  108. package/dist/ecweb/message-context-service.js +110 -0
  109. package/dist/index.js +76 -14
  110. package/dist/ipc.js +170 -12
  111. package/dist/paths.js +4 -0
  112. package/dist/proxy/command.js +122 -0
  113. package/dist/proxy/ipc-service.js +68 -0
  114. package/dist/proxy/manager.js +485 -0
  115. package/dist/proxy/service-supervisor.js +603 -0
  116. package/dist/response-system/engines/v1/proactive-flow.js +16 -6
  117. package/dist/utils/cross-platform.js +14 -0
  118. package/dist/utils/ecweb-supervisor.js +258 -83
  119. package/dist/utils/error-utils.js +2 -2
  120. package/dist/utils/logger.js +24 -5
  121. package/dist/utils/package-version-info.js +4 -2
  122. package/kits/docs/channels/aun.md +9 -0
  123. package/kits/docs/evolcore/agent.md +1 -1
  124. package/kits/docs/evolcore/config.md +17 -6
  125. package/kits/docs/evolcore/contact.md +3 -0
  126. package/kits/docs/evolcore/fs.md +11 -0
  127. package/kits/docs/evolcore/memory-architecture.md +2 -2
  128. package/kits/docs/evolcore/memory-consolidation.md +32 -8
  129. package/kits/docs/evolcore/memory.md +1 -1
  130. package/kits/docs/evolcore/menu-protocol.md +4 -0
  131. package/kits/docs/evolcore/model.md +23 -20
  132. package/kits/docs/evolcore/msg.md +4 -7
  133. package/kits/migrations/migrate-contact-book-v2.mjs +30 -11
  134. package/kits/schemas/_meta.json +37 -4
  135. package/kits/schemas/agent-config.schema.13.json +8 -3
  136. package/kits/schemas/agent-config.schema.16.json +891 -0
  137. package/kits/schemas/daemon.schema.9.json +366 -0
  138. package/kits/schemas/defaults.schema.5.json +406 -127
  139. package/kits/schemas/relation-config.schema.11.json +260 -0
  140. package/kits/schemas/role-config.schema.1.json +7 -7
  141. package/kits/skills/.switches.json +3 -7
  142. package/kits/skills/ec-service-proxy/SKILL.md +118 -0
  143. package/kits/skills/ec-trigger/SKILL.md +13 -5
  144. package/kits/skills/personal-assistant/SKILL.md +176 -0
  145. package/kits/skills/personal-assistant/references/01-workspace-spec.md +333 -0
  146. package/kits/skills/personal-assistant/references/02-bootstrap.md +205 -0
  147. package/kits/skills/personal-assistant/references/03-data-flow-and-gaps.md +177 -0
  148. package/kits/skills/personal-assistant/references/04-frontend-contract.md +439 -0
  149. package/kits/skills/personal-assistant/references/05-directory-reference.md +292 -0
  150. package/kits/skills/personal-assistant/references/06-render-config.md +350 -0
  151. package/kits/skills/personal-assistant/schema/workspace.schema.json +85 -0
  152. package/kits/skills/personal-assistant/schema/workspace.v1.json +66 -0
  153. package/kits/skills/personal-assistant/scripts/archive.mjs +154 -0
  154. package/kits/skills/personal-assistant/scripts/check.mjs +114 -0
  155. package/kits/skills/personal-assistant/scripts/index-rebuild.mjs +252 -0
  156. package/kits/skills/personal-assistant/scripts/ingest.mjs +344 -0
  157. package/kits/skills/personal-assistant/scripts/init.mjs +270 -0
  158. package/kits/skills/personal-assistant/scripts/lib/apply.mjs +92 -0
  159. package/kits/skills/personal-assistant/scripts/lib/schema.mjs +96 -0
  160. package/kits/skills/personal-assistant/scripts/lib/time.mjs +28 -0
  161. package/kits/skills/personal-assistant/scripts/migrate.mjs +172 -0
  162. package/kits/skills/personal-assistant/scripts/search.mjs +172 -0
  163. package/kits/skills/personal-assistant/scripts/verify.mjs +196 -0
  164. package/kits/skills/personal-assistant/templates/INDEX.md.tpl +24 -0
  165. package/kits/skills/personal-assistant/templates/README.md.tpl +108 -0
  166. package/kits/skills/personal-assistant/triggers/ingest-daily.json +23 -0
  167. package/kits/skills/personal-assistant/triggers/memory-consolidate.json +23 -0
  168. package/kits/skills/personal-assistant/triggers/report-daily.json +23 -0
  169. package/kits/skills/personal-assistant/triggers/report-weekly.json +23 -0
  170. package/kits/templates/memory-consolidation/forget.md +19 -6
  171. package/kits/templates/memory-consolidation/notes.md +1 -1
  172. package/kits/templates/memory-consolidation/profile.md +2 -2
  173. package/kits/templates/memory-consolidation/promote.md +20 -3
  174. package/kits/templates/roles/member.json +8 -1
  175. package/kits/templates/system-fragments/baseagent.md +2 -2
  176. package/kits/templates/system-fragments/memory.md +4 -4
  177. package/package.json +6 -2
@@ -0,0 +1,177 @@
1
+ # 数据流转机制与能力缺口
2
+
3
+ > 版本:0.1(草案,待评审)
4
+ > 记录时间:2026-10-27
5
+ > 性质:**实测记录 + 缺口清单**,不是设计文档。所有"不可行"都有原始报错为据。
6
+
7
+ ---
8
+
9
+ ## 1. 三种驱动力
10
+
11
+ 整个系统只用三种驱动力,没有第四种:
12
+
13
+ | 驱动力 | 管什么 | 特征 | 失败表现 |
14
+ |---|---|---|---|
15
+ | **触发器**(EvolCore) | 什么时候做 | 定时 cron、事件订阅 | 不触发 / 触发但空跑 |
16
+ | **模型**(会话) | 这次该做什么 | 判断、取舍、生成内容 | 判断错、漏做、做多 |
17
+ | **脚本**(技能) | 具体怎么做 | 确定性、可测试、幂等 | 报错、写坏、重复写 |
18
+
19
+ **裁决原则**:能用脚本做的,不交给模型(模型不确定、贵、慢);需要判断的,不交给脚本(规则写不全);只在需要调度时才用触发器。
20
+
21
+ ---
22
+
23
+ ## 2. 每条数据流由谁驱动
24
+
25
+ | # | 数据流 | 触发器 | 模型 | 脚本 |
26
+ |---|---|---|---|---|
27
+ | 1 | 对话正文落地 | ✅ 每日 cron + `session:idle` | 判断落地范围、补漏 | 写文件、算摘要、写 manifest |
28
+ | 2 | 记忆导出与演进 | ✅ 每日 cron | 判断哪条该合并、该废弃 | 写文件、标记 superseded |
29
+ | 3 | 手机观察落地 | ✅ 每日 cron | 判断哪些数据类型值得取 | 申请授权、下载、解包 |
30
+ | 4 | 用户投喂(口述/链接/文件) | ❌ 不需要(消息到达即触发) | 判断归类、写摘要 | 写文件、更新索引 |
31
+ | 5 | 会议落地 | ✅ 聆听结束事件 | 判断是否值得提炼 | 写转写、生成 meta |
32
+ | 6 | 日报/周报/月报 | ✅ cron | 生成正文(**必须模型**) | 汇总数据、渲染模板 |
33
+ | 7 | 索引重建 | ✅ 每日 cron | 不需要 | 全量扫描 frontmatter |
34
+ | 8 | 冷热归档 | ✅ 每月 cron | 不需要 | 移动文件、更新索引 |
35
+ | 9 | 完整性校验 | ✅ 每周 cron | 不需要 | 比对 sha256 |
36
+
37
+ **结论:模型只负责"第 6 项"这类必须生成文本的地方,以及归类的判断;其余全部交给脚本。**
38
+
39
+ 这是成本和稳定性的关键——如果每条流都过一遍模型,一天几十次调用,既贵又漂移。
40
+
41
+ ---
42
+
43
+ ## 3. 实测记录(2026-10-27)
44
+
45
+ ### 3.1 已验证可用
46
+
47
+ | 机制 | 验证方式 | 结果 |
48
+ |---|---|---|
49
+ | cron 定时触发 | 查看现有 3 个触发器运行记录 | ✅ 正常(8:30 / 10-18 点每 2 小时 / 21:30) |
50
+ | `target-session` 拉起会话 | 日历巡检实际执行 | ✅ 12:00、14:00 均正常返回 |
51
+ | `--file` 导入 Trigger V3 JSON | 实建一个 `probe-script-feasibility` 后删除 | ✅ 导入成功,字段完整 |
52
+ | `ec thread history` 读对话 | 实读主话题 527 条、跨对端 259 条 | ✅ **推荐用法**;按话题切分,字段齐全 |
53
+ | `ec thread peers / list` | 实测 | ✅ 19 个对端、30 个话题,JSON 结构完整 |
54
+ | `ec thread history --after/--before` | 实测 | ✅ 时间过滤有效,返回升序 |
55
+ | 位置能力 `location/current` | 实际调用 4 次 | ✅ 成功,但返回缓存值(见 G5) |
56
+ | 日历能力 `calendar/manage` | 多次调用 | ✅ 成功(注意:`list` 不接受 `calendar_id`) |
57
+
58
+ ### 3.2 实测失败
59
+
60
+ **G1|Windows 上脚本触发器被沙箱拒绝**
61
+
62
+ ```json
63
+ {
64
+ "type": "run.failed",
65
+ "error": {
66
+ "message": "Windows sandbox cannot prove scoped read isolation;
67
+ Trigger script execution is refused: read isolation is not enforced"
68
+ }
69
+ }
70
+ ```
71
+
72
+ - **复现**:创建 `--exec script` 的触发器并触发,约 8 秒内失败
73
+ - **原因**:Windows 需要「支持受限读取策略的原生 Codex CLI + 宿主已准备好的 elevated sandbox」,当前环境无法证明读隔离
74
+ - **注意**:系统自带的 `__memory-consolidation-check` 也是 script 类型却能跑,因为它是 **daemon 自有**触发器(走宿主执行路径),不受此限制
75
+
76
+ **G2|观察数据在托管会话中读不到**
77
+
78
+ ```bash
79
+ ec rpc --as toleiliang8.agentid.pub --params '{"method":"storage.get_by_share",...}'
80
+ # ❌ [NOT_ALLOWED] Command rpc is not available in a managed Agent task
81
+
82
+ ec fs cat leiliang.agentid.cn:/.evol/observation-access/v1/snapshots/.../manifest-0001.json
83
+ # ❌ forbidden
84
+ ```
85
+
86
+ - 授权本身能拿到(`personal/observations` 返回 `status: active`、`grant_id`、`share_id`)
87
+ - **但拿到授权也读不了内容**——读取路径被托管会话策略挡住了
88
+
89
+ **G3|跨对端历史导出受限 —— 已解除(2026-10-28)**
90
+
91
+ 原判断基于 `ec msg history`。改用 `ec thread history <peer> --self <selfAid>` 后可跨对端读取,
92
+ 实测成功读到其他对端的 259 条历史。
93
+
94
+ > 注意:不带 `--self` 会报 `✗ peer is required`。
95
+
96
+ ### 3.3 有效但需注意
97
+
98
+ | 现象 | 说明 |
99
+ |---|---|
100
+ | `ec trigger show <id>` 报错 | `Cannot find module dist/cli/trigger-command.js`。`list`/`create`/`delete` 正常,只有 `show` 坏 |
101
+ | `calendar/manage` 的 `list` 不接受 `calendar_id` | 带上就返回 `params_invalid`,去掉即可 |
102
+ | 能力调用需要 `--device-id` | 不带报 `ABILITY_DEVICE_REQUIRED`;两台设备中只有一台在线 |
103
+ | `--return required` 可能返回 `message_expired` | 设备不在线时的表现,不是参数错误 |
104
+
105
+ ---
106
+
107
+ ## 4. 缺口清单
108
+
109
+ | 编号 | 缺口 | 影响 | 临时方案 | 正式方案 |
110
+ |---|---|---|---|---|
111
+ | **G1** | 脚本触发器在 Windows 不可用 | 定时任务只能走会话,成本高一个量级 | 全部改用 `trigger-session`,由会话执行脚本 | EvolCore 提供可用沙箱,或提供 daemon 级"受信脚本触发器"注册 |
112
+ | **G2** | 观察数据读不到 | 位置/聆听/照片三类最有价值的原料只能存不能取 | 落空目录占位,保留接口 | EvolCore 开放托管会话读取观察数据的命令或 API |
113
+ | ~~**G3**~~ | ~~跨对端历史受限~~ | **已解除**:`ec thread history <peer> --self` 可读 | — | — |
114
+ | **G4** | 事件 `session:idle` 未实测 | "会话结束落地"可能不成立 | 退回每日全量 | 实测并调参(idle 阈值、过滤条件) |
115
+ | **G5** | 位置能力返回缓存值 | 位置轨迹精度不可信 | 明确标注 `cached: true` | 能力侧支持强制刷新定位 |
116
+ | **G6** | `trigger-session` 类型未实测 | 全部触发器依赖它,是单点风险 | 先小范围试 | 实测 + 准备 `target-session` 兜底 |
117
+ | **G7** | 记忆导出路径未验证 | 记忆落地可能做不了 | 从会话上下文重建 | 确认 `agents/<aid>/personal/memory` 可读,或提供导出命令 |
118
+ | ~~**G8**~~ | ~~幂等键不确定~~ | **已解除**:`msgId` 稳定唯一,作为幂等键 | — | — |
119
+ | **G9** | 大文件/录音的引用如何取回未验证 | 引用存了但可能取不回 | 只存元数据 | 验证 `storage download` 对引用路径的可用性 |
120
+ | **G10** | 并发写同一天的锁机制未验证 | cron 与事件撞车可能写脏 | 单写者串行 | 实测文件锁在 Windows 的行为 |
121
+ | **G12** | 话题历史没有文本搜索 | 只能按时间翻,找一句话要翻几百条 | `search.mjs` 落地后本地检索 | EvolCore 给 `history` 加 `--search` |
122
+
123
+ ### 4.1 `ec thread history` 的三个坑(实测)
124
+
125
+ | 坑 | 表现 | 正确用法 |
126
+ |---|---|---|
127
+ | `--limit N` 是「最近 N 条」 | `--after 0 --limit 3` 返回的是最新 3 条,不是最早 3 条 | 回填必须用 `--before <ts>` 往前翻 |
128
+ | 跨对端必须带 `--self` | 不带报 `✗ peer is required` | `ec thread history <peer> --self <selfAid>` |
129
+ | 非主话题必须用 `peer/threadId` | 只传 `thread-xxx` 报 `peer is required` | `ec thread history <peer>/<thread-xxx> --self <aid>` |
130
+
131
+ ---
132
+
133
+ ## 5. 三份文档各自的问题
134
+
135
+ | 文档 | 已知问题 | 优先级 |
136
+ |---|---|---|
137
+ | `01-workspace-spec.md` | ① `track/` 四类数据的字段定义还没定;② `_archive/` 的索引分片规则没写细;③ 没有定义 `capture/files/` 里大文件的引用格式 | 中 |
138
+ | `02-bootstrap.md` | ① 触发器清单是"理想清单",受 G1/G4/G6 影响,实际能装的更少;② 升级迁移只给了原则,没有具体迁移脚本设计 | 高 |
139
+ | `03-data-flow-and-gaps.md`(本文) | ① G5–G10 尚未实测,结论可能变;② 没有给出每条的验证步骤脚本 | 高 |
140
+
141
+ ---
142
+
143
+ ## 6. 待验证清单(按优先级)
144
+
145
+ - [ ] **G6**:`trigger-session` 能否正常拉起并 silent 返回 → 影响全部触发器
146
+ - [ ] **G4**:`session:idle` 事件的 payload 是否含 `sessionId`,过滤能否生效
147
+ - [ ] **G8**:`ec msg history --format json` 是否返回可作幂等键的字段
148
+ - [ ] **G7**:`.evolcore/agents/<aid>/personal/memory/` 是否可读
149
+ - [ ] **G10**:Windows 下文件锁的行为
150
+ - [ ] **G5**:位置能力是否有强制刷新参数
151
+ - [ ] **G9**:存储引用的可下载性
152
+
153
+ ---
154
+
155
+ ## 7. 最低可行版本(MVP)的边界
156
+
157
+ 先跑起来,跑的是这个范围:
158
+
159
+ **做:**
160
+ - 目录骨架 + README + INDEX
161
+ - 对话正文落地(当前对端)
162
+ - 用户投喂的笔记、链接、文件
163
+ - 日报 / 周报 / 月报
164
+ - 记忆整理(从会话上下文重建,不依赖导出)
165
+ - 索引重建、归档、清单校验
166
+
167
+ **不做(占位等 G1/G2/G3 解决):**
168
+ - 手机观察数据(位置、聆听、照片)
169
+ - 全量跨对端历史
170
+ - 脚本型触发器
171
+
172
+ **MVP 的验收标准**:连续跑 7 天,每天三件事成立——
173
+ 1. 当天对话在 `capture/conversation/` 里能查到
174
+ 2. 每天晚上有日报
175
+ 3. `_manifest/` 连续无缺失
176
+
177
+ 七天后带着真实问题回来迭代,比纸面设计再完美都值钱。
@@ -0,0 +1,439 @@
1
+ # 前端数据契约
2
+
3
+ > 版本:v1(对应工作区 schema v1)
4
+ > 读者:前端设计师 / 前端工程师
5
+ > 用途:照着这份文档就能把数据读出来并渲染
6
+
7
+ ---
8
+
9
+ ## 1. 只有一种数据形态:Markdown
10
+
11
+ **前端读的就是 md 文件本身,没有第二份数据。**
12
+
13
+ ```
14
+ 文件 = YAML frontmatter(元数据) + Markdown 正文(内容)
15
+ ```
16
+
17
+ - **frontmatter 是契约**:列表页需要的所有字段都在这里,前端解析 YAML 拿到结构
18
+ - **正文是内容**:详情页直接渲染 markdown
19
+ - **目录是路由**:路径决定分组和导航,不需要额外的索引文件
20
+
21
+ **没有 JSON 视图层,也不会有。** 原因是设计上的硬约束:
22
+
23
+ | 如果另做一份 JSON | 后果 |
24
+ |---|---|
25
+ | 大模型要输出两份 | 同一份内容写两遍,token 翻倍 |
26
+ | 要让模型保证 JSON 合法 | 得配 Schema 校验、重试、兜底——把不确定性引进来 |
27
+ | 两份会漂移 | 正文改了 JSON 没改,前端和实际不一致 |
28
+ | 多一层同步 | 每次写入都要跑一次转换,多一个会坏的部件 |
29
+
30
+ **结论:frontmatter 就是数据库,markdown 就是内容,一物一份。**
31
+
32
+ ---
33
+
34
+ ## 2. 目录即路由
35
+
36
+ ```
37
+ <workspace>/
38
+ ├── README.md 工作区说明(前端可做「关于」页)
39
+ ├── INDEX.md 全量条目索引(人读,前端不用)
40
+ ├── capture/ 原料层
41
+ │ ├── conversation/ 对话正文
42
+ │ ├── notes/ 随笔
43
+ │ ├── links/ 链接与文章
44
+ │ ├── files/ 收到的文件
45
+ │ ├── scene/ 看现场(照片+位置)
46
+ │ ├── listening/ 持续聆听
47
+ │ ├── meeting/ 会议原料
48
+ │ └── track/ 行为轨迹
49
+ ├── output/ 产出层 ← **前端主要读这里**
50
+ │ ├── reports/ 日/周/月/季/年报
51
+ │ ├── meetings/ 会议总结
52
+ │ ├── tasks/ 任务
53
+ │ └── knowledge/ 画像 / 记忆 / 主题
54
+ └── .assistant/ 运行时状态(前端不读)
55
+ ```
56
+
57
+ ### 2.1 目录渲染配置
58
+
59
+ **前端不为每个目录单独写页面。** 所有目录共用一套「列表 / 详情」渲染器,渲染差异由每个目录里的 `render.yaml` 声明。
60
+
61
+ ```
62
+ 目录 + render.yaml → 标准渲染器 → 列表页 / 详情页
63
+ ```
64
+
65
+ 渲染器从 `render.yaml` 读取:展示名(`title`)、布局(`layout`)、卡片显示哪几个字段(`fields`)、默认排序(`sort`)、默认过滤(`filter`)、详情正文渲染方式(`detail.body`)。没有 `render.yaml` 的目录用内置默认值,同样能跑。
66
+
67
+ **完整规范、五种 layout(`list` / `board` / `cards` / `gallery` / `chat`)的示意、各目录的建议配置及示例文件,见 `06-render-config.md`。**
68
+
69
+ 此处只需知道:所有目录的扫描方式都一样——`<dir>/**/*.md`,取 frontmatter 里的 `type` 和其他字段,再按 `render.yaml` 决定怎么画。
70
+
71
+ ### 2.2 时间层级
72
+
73
+ ```
74
+ output/reports/daily/2026/2026-10-27.md ← 报告按 年/
75
+ capture/conversation/2026/10/27/<threadId>/ ← 对话按 年/月/日/
76
+ output/knowledge/memory/facts/2026/10/*.md ← 记忆按 年/月/
77
+ ```
78
+
79
+ **规则**:条目多、按天查的用 `年/月/日/`;条目少、按主题查的用 `年/` 或 `年/月/`。
80
+ 前端做导航时,**目录层级就是面包屑**,不要自己造层级。
81
+
82
+ ---
83
+
84
+ ## 3. 文件命名
85
+
86
+ ```
87
+ <日期>-<时分>-<标题>.md
88
+ 2026-10-27-1200-会议模式界面.md
89
+ ```
90
+
91
+ - 日期 `YYYY-MM-DD`,时分 24 小时制 `HHmm`
92
+ - 标题 ≤ 20 字,无空格、无标点
93
+ - **日期+时分来自文件名,不一定要再放进 frontmatter**——但 `date` 字段必须有(见下)
94
+
95
+ ---
96
+
97
+ ## 4. frontmatter 是唯一的元数据契约
98
+
99
+ ### 4.1 通用字段(所有 md 必带)
100
+
101
+ ```yaml
102
+ ---
103
+ id: 2026-10-27-1200-会议模式界面
104
+ date: 2026-10-27T12:00:00+08:00
105
+ type: note
106
+ tags: [标签1, 标签2]
107
+ source: 自己
108
+ ---
109
+ ```
110
+
111
+ | 字段 | 类型 | 必填 | 说明 |
112
+ |---|---|---|---|
113
+ | `id` | string | ✅ | 全局唯一。前端用作列表 key |
114
+ | `date` | ISO8601 字符串 | ✅ | **带时区偏移**,如 `+08:00` |
115
+ | `type` | enum | ✅ | 见 §5,决定渲染模板 |
116
+ | `tags` | string[] | ✅ | 可为空数组 |
117
+ | `source` | string | ✅ | 来源。`自己` / 人名 / `ec-thread:<id>` / 相对路径 |
118
+
119
+ ### 4.2 解析要点(前端必读)
120
+
121
+ | 事项 | 说明 |
122
+ |---|---|
123
+ | **YAML 解析器** | 用标准 YAML 库,不要自己写正则。`tags` 可能是 `[a, b]` 行内数组,也可能是多行 `- a` 列表 |
124
+ | **时间** | `date` 是**带时区的字符串**。前端自行转 Date 对象;比较/排序前统一转 epoch |
125
+ | **缺字段** | 不要崩。缺失按「无」处理,`tags` 缺失当空数组 |
126
+ | **正文起点** | 第二个 `---` 之后的全部内容 |
127
+ | **不可信内容** | frontmatter 和正文都是助理/AI 生成的,**渲染前必须转义**,不要当 HTML 插入 |
128
+
129
+ ### 4.3 每个 type 的专属字段
130
+
131
+ #### `type: task`
132
+
133
+ ```yaml
134
+ ---
135
+ id: task-2026-10-28-001
136
+ date: 2026-10-28T08:00:00+08:00
137
+ type: task
138
+ tags: [开发]
139
+ source: capture/conversation/2026/10/28/xxx
140
+ status: in_progress
141
+ horizon: short
142
+ priority: P1
143
+ due_at: 2026-10-29T00:00:00+08:00
144
+ completed_at: null
145
+ owner_note: null
146
+ stale_checks: 0
147
+ ---
148
+
149
+ # 补充历史回填
150
+
151
+ 正文:为什么做、做到哪一步。
152
+ ```
153
+
154
+ | 字段 | 取值 | 渲染 |
155
+ |---|---|---|
156
+ | `status` | `pending` / `in_progress` / `blocked` / `done` / `dropped` | 看板分列 |
157
+ | `horizon` | `today` / `short` / `long` / `queue` | 分组标签 |
158
+ | `priority` | `P0` / `P1` / `P2` / null | 排序与着色 |
159
+ | `due_at` | ISO8601 / null | 逾期判断 |
160
+ | `completed_at` | ISO8601 / null | 完成时间 |
161
+ | `owner_note` | string / null | 非空时显示「主人在处理」,弱化提醒 |
162
+ | `stale_checks` | number | `>=2` 且未完成 → 提示「建议拆分」 |
163
+
164
+ **逾期由前端算**:`due_at < now && status !== 'done'`。
165
+
166
+ #### `type: report`
167
+
168
+ ```yaml
169
+ ---
170
+ id: report-daily-2026-10-27
171
+ date: 2026-10-27T23:50:00+08:00
172
+ type: report
173
+ tags: [日报]
174
+ source: capture/conversation/2026/10/27/
175
+ period: 2026-10-27
176
+ report_type: daily
177
+ summary: 完成技能骨架;落地对话 168 条。
178
+ ---
179
+ ```
180
+
181
+ | 字段 | 说明 |
182
+ |---|---|
183
+ | `period` | **覆盖的周期**,不是生成时间。`2026-10-27` / `2026-W43` / `2026-10` / `2026-Q4` / `2026` |
184
+ | `report_type` | `daily` / `weekly` / `monthly` / `quarterly` / `yearly` |
185
+ | `summary` | 一两句话,列表页直接显示,**不用前端去正文里抓** |
186
+
187
+ **排序用 `period`,不是 `date`**。10-28 写的 10-27 日报,`period` 是 `2026-10-27`。
188
+
189
+ #### `type: meeting`
190
+
191
+ ```yaml
192
+ ---
193
+ id: meeting-2026-10-26-001
194
+ date: 2026-10-26T14:00:00+08:00
195
+ type: meeting
196
+ tags: [产品评审]
197
+ source: capture/meeting/2026/10/26-产品评审会/
198
+ duration_min: 68
199
+ participants: [leiliang, 李文江, 蒋先福]
200
+ summary: 确定 Q4 三个方向。
201
+ transcript: capture/meeting/2026/10/26-产品评审会/transcript.jsonl
202
+ action_items: 4
203
+ ---
204
+ ```
205
+
206
+ | 字段 | 说明 |
207
+ |---|---|
208
+ | `duration_min` | 时长(分钟),整数 |
209
+ | `participants` | 显示名数组 |
210
+ | `transcript` | 原始转写路径,可能为 null |
211
+ | `action_items` | 待办条数,可做角标 |
212
+
213
+ #### `type: profile` / `memory` / `topic`
214
+
215
+ ```yaml
216
+ ---
217
+ id: fact-2026-10-27-常驻上海
218
+ date: 2026-10-27T12:00:00+08:00
219
+ type: memory
220
+ tags: [位置]
221
+ source: capture/conversation/2026/10/27/
222
+ memory_kind: fact
223
+ status: active
224
+ supersedes: null
225
+ superseded_by: null
226
+ summary: 手机定位稳定在闵行马桥一带。
227
+ ---
228
+ ```
229
+
230
+ | 字段 | 说明 |
231
+ |---|---|
232
+ | `memory_kind` | `rule` / `fact` / `entity` / `episode`(仅 memory) |
233
+ | `status` | `active` / `superseded` |
234
+ | `supersedes` | 本条目取代了哪个旧条目 id |
235
+ | `superseded_by` | 本条目被哪个新条目取代 |
236
+
237
+ **前端默认只显示 `status: active`。**`superseded` 的放进「历史版本」折叠区——**这是本系统的特色:旧记忆不删除,能看演变过程**。
238
+
239
+ #### `type: conversation`
240
+
241
+ ```yaml
242
+ ---
243
+ id: main:leiliang.agentid.cn:toleiliang8.agentid.pub-2026-10-27
244
+ date: 2026-10-27T00:00:00+08:00
245
+ type: conversation
246
+ tags: [对话]
247
+ source: ec-thread:main:leiliang.agentid.cn:toleiliang8.agentid.pub
248
+ thread_id: main:leiliang.agentid.cn:toleiliang8.agentid.pub
249
+ peer: leiliang.agentid.cn
250
+ count: 94
251
+ ---
252
+ ```
253
+
254
+ #### `type: scene`(看现场)
255
+
256
+ ```yaml
257
+ ---
258
+ id: 2026-10-27-0919-现场
259
+ date: 2026-10-27T09:19:03+08:00
260
+ type: scene
261
+ tags: [现场]
262
+ source: 设备
263
+ photo: media/scene/2026-10-27-0919.jpg
264
+ location:
265
+ lat: 31.047711
266
+ lon: 121.348993
267
+ accuracy_m: 25
268
+ address: 上海市闵行区马桥镇森林溪谷别墅
269
+ summary: 阳台外是别墅区,桌上一台笔记本。
270
+ ---
271
+ ```
272
+
273
+ ⚠️ `photo` 指向的媒体本体当前**取不到**(见 §8)。
274
+
275
+ ---
276
+
277
+ ## 5. type 一览
278
+
279
+ | type | 目录 | 渲染模板 |
280
+ |---|---|---|
281
+ | `task` | `output/tasks/` | 看板卡片 / 列表行 |
282
+ | `report` | `output/reports/{level}/` | 列表行 + 详情正文 |
283
+ | `meeting` | `output/meetings/` | 列表行 + 详情正文 |
284
+ | `profile` | `output/knowledge/profile/` | 卡片 + 详情正文 |
285
+ | `memory` | `output/knowledge/memory/` | 列表行(按 memory_kind 分组) |
286
+ | `topic` | `output/knowledge/topics/` | 卡片 + 详情正文 |
287
+ | `conversation` | `capture/conversation/` | 会话流(左右分栏) |
288
+ | `scene` | `capture/scene/` | 图文卡 |
289
+ | `note` | `capture/notes/` | 纯文本卡 |
290
+ | `link` | `capture/links/` | 链接卡(含摘要) |
291
+ | `listening` | `capture/listening/` | 音频卡(媒体不可用) |
292
+
293
+ ---
294
+
295
+ ## 6. 正文渲染
296
+
297
+ ### 6.1 标准 markdown
298
+
299
+ 用任意 markdown 渲染器,支持:标题、列表、有序列表、表格、引用、代码块、行内代码、粗体斜体、链接、分隔线。
300
+
301
+ **必须做 HTML 转义**:正文是 AI 生成的,可能含 `<script>` 之类的内容,绝不能直接 `innerHTML`。
302
+
303
+ ### 6.2 内部链接
304
+
305
+ 正文里的相对路径链接(如 `../../capture/...`),前端需要:
306
+
307
+ 1. 解析为工作区相对路径
308
+ 2. 映射到前端路由(如果目标在工作区内)
309
+ 3. 不可达的链接渲染成纯文本,不要做成死链
310
+
311
+ ### 6.3 图片
312
+
313
+ ```markdown
314
+ ![现场](../../media/scene/2026-10-27-0919.jpg)
315
+ ```
316
+
317
+ 相对路径 → 需要映射到静态资源服务。当前**媒体服务未开放**,图片会加载失败,需要占位图。
318
+
319
+ ### 6.4 对话类正文的特殊结构
320
+
321
+ `capture/conversation/**/transcript.md` 的正文是固定的消息流格式:
322
+
323
+ ```markdown
324
+ **2026-10-27 09:19:27** ← `leiliang.agentid.cn`
325
+
326
+ 以下是我对你的直接提问或指令……
327
+
328
+ **2026-10-27 09:19:49** → `toleiliang8.agentid.pub`
329
+
330
+ 上海宋庆龄故居纪念馆,具体如下……
331
+ ```
332
+
333
+ 规则:每段以 `**时间** 箭头 \`发送方\`` 开头,`←` 是收到的,`→` 是发出的。
334
+
335
+ **如果要做成聊天气泡**,可以按这个模式切分;**如果只是展示**,直接渲染即可。
336
+
337
+ 同一目录下还有 `transcript.jsonl`,一行一条消息,字段:
338
+ ```json
339
+ {"msgId":"...","dir":"in|out","from":"...","to":"...","ts":1793000000000,"time":"2026/10/27 09:19:27","type":"text","text":"..."}
340
+ ```
341
+ **需要精确做气泡流时才读它**;普通展示用 md 就够。
342
+
343
+ ---
344
+
345
+ ## 7. 列表页怎么拿数据
346
+
347
+ 前端需要「列出所有任务」「列出所有报告」,做法是**扫目录 + 解析 frontmatter**:
348
+
349
+ ```
350
+ 1. 列出 output/tasks/**/*.md
351
+ 2. 逐个读文件开头(读到第二个 --- 就停,不用读全文)
352
+ 3. 解析 YAML 拿元数据
353
+ 4. 按规则排序渲染
354
+ 5. 点进去再读全文
355
+ ```
356
+
357
+ **性能建议**:
358
+
359
+ | 手段 | 说明 |
360
+ |---|---|
361
+ | 只读头部 | frontmatter 后面的正文不用读,读 2KB 通常够 |
362
+ | 缓存 | 用「路径 + mtime + size」做缓存 key,变了才重解析 |
363
+ | 懒加载 | 列表只解析 frontmatter,正文进详情页才读 |
364
+ | 目录分片 | 按 `年/月` 分目录,只加载当前视图需要的月份 |
365
+
366
+ ---
367
+
368
+ ## 8. 当前不可用的部分
369
+
370
+ **前端要据此隐藏或置灰入口,不要让用户点进去看到空白。**
371
+
372
+ | 功能 | 状态 | 原因 |
373
+ |---|---|---|
374
+ | 现场照片查看 | ❌ | 媒体本体在存储层,托管会话读不到 |
375
+ | 聆听音频 / 转写 | ❌ | 同上 |
376
+ | 位置轨迹地图 | ❌ | 同上 |
377
+ | 手机使用统计 | ❌ | 同上 |
378
+
379
+ 判断依据:`capture/scene/`、`capture/listening/`、`capture/track/` 目录存在但**没有内容**。
380
+ 前端可以做兜底:目录为空时显示「当前环境未开放此数据」。
381
+
382
+ ---
383
+
384
+ ## 9. 交互 → 写操作
385
+
386
+ 前端**不直接写文件**。
387
+
388
+ | 用户动作 | 做法 |
389
+ |---|---|
390
+ | 新建任务 | 发一句话给助理:「记一条任务:xxx」 |
391
+ | 标记完成 | 「把 xxx 标记完成」 |
392
+ | 改优先级 | 「xxx 提到 P0」 |
393
+
394
+ **为什么**:直接改文件和助理的下一次写入会打架,且绕过 id 生成与索引更新。
395
+
396
+ 前端可以做乐观 UI:点击后立即打勾,等下一次扫描文件时确认。
397
+
398
+ ---
399
+
400
+ ## 10. 版本与兼容
401
+
402
+ | 变化 | 处理 |
403
+ |---|---|
404
+ | **新增 frontmatter 字段** | 前端忽略未知字段即可,无需改动 |
405
+ | **字段改名或语义变更** | 工作区 `workspace_version` 递增,前端按版本适配 |
406
+ | **目录结构调整** | 同上;由 migrate 脚本自动修正旧工作区 |
407
+
408
+ **前端自查清单**:
409
+
410
+ 1. 所有列表项都用 `id` 做 key
411
+ 2. `date` / `due_at` 等按 ISO8601 带时区解析,不假设固定格式
412
+ 3. 缺字段不崩
413
+ 4. 正文渲染做了 HTML 转义
414
+ 5. `status: superseded` 的知识条目默认隐藏
415
+ 6. 空目录显示「暂无数据」而不是空白页
416
+
417
+ ---
418
+
419
+ ## 11. 一页速查
420
+
421
+ ```
422
+ 列表页 → 扫目录 **/*.md → 读头部 → 解析 YAML → 按 date/period 排序
423
+ 详情页 → 同一个文件,渲染第二个 --- 之后的正文
424
+ 对话流 → capture/conversation/年/月/日/<threadId>/transcript.md
425
+ 精确消息 → 同目录 transcript.jsonl
426
+ 写操作 → 一律走对话
427
+ 媒体 → 当前不可用,显示占位
428
+ ```
429
+
430
+ ---
431
+
432
+ ## 12. 未定项(需要产品确认)
433
+
434
+ 1. **文件读取通道**:本地文件系统直读,还是起一个只读服务?未定。
435
+ 2. **媒体服务**:照片与音频需要独立通道,受当前能力限制。
436
+ 3. **搜索**:`scripts/search.mjs` 是命令行工具。前端做搜索框需要包一层,或前端自己在内存里过滤。
437
+ 4. **实时更新**:当前是「重新扫描文件」。要即时感需要文件监听或事件推送。
438
+
439
+ 以上都不影响 v1 契约,先按「扫目录 + 解析 frontmatter」实现即可。