@furongjun1999/dsh-memory 0.9.12 → 0.9.14

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 (35) hide show
  1. package/README.md +21 -4
  2. package/codebuddy/CODEBUDDY.md +8 -3
  3. package/codebuddy/README.md +92 -92
  4. package/docs/discipline/templates/zcode-user.md.tmpl +52 -52
  5. package/docs//345/267/245/344/275/234/347/272/252/345/276/213_/350/256/244/347/237/245/345/233/276/346/235/241/347/233/256_v1.1.json +488 -461
  6. package/docs//350/247/204/350/214/203/AI/347/274/226/347/250/213/351/200/232/347/224/250/350/247/204/350/214/203_/347/201/265/346/236/242/351/200/202/351/205/215.md +45 -45
  7. package/dsh/README.md +82 -82
  8. package/lib/hooks.d.ts +7 -1
  9. package/lib/hooks.js +62 -31
  10. package/lib/index.js +4 -1
  11. package/md_cg/config_registry_bulk.py +2 -0
  12. package/md_cg/config_validate.py +463 -461
  13. package/md_cg/conformance_core.py +28 -0
  14. package/md_cg/consistency.py +9 -2
  15. package/md_cg/mcp_server.py +91 -0
  16. package/md_cg/mdcg.py +162 -7
  17. package/md_cg/mdcos.py +53 -6
  18. package/md_cg/nodefile.py +39 -1
  19. package/md_cg/op_table.py +1 -0
  20. package/md_cg/relations.py +91 -0
  21. package/md_cg/scrub.py +20 -3
  22. package/md_cg/test_exact_text_cache.py +12 -4
  23. package/md_cg/test_issue218_postcondition_value_blind.py +4 -2
  24. package/md_cg/test_issue644_637_636.py +84 -0
  25. package/md_cg/test_issue650_658_f26.py +98 -0
  26. package/md_cg/test_issue659_r26_batch2.py +74 -0
  27. package/md_cg/test_issue665_scrub_process_records.py +59 -0
  28. package/md_cg/test_issue669_ccg_empty_colon.py +69 -0
  29. package/md_cg/test_issue672_validity_scope.py +47 -0
  30. package/md_cg/version_anchor.py +160 -0
  31. package/package.json +2 -2
  32. package/src/hooks.ts +64 -31
  33. package/src/index.ts +4 -1
  34. package/zcode/AGENTS.md +8 -3
  35. package/zcode/README.md +41 -41
package/README.md CHANGED
@@ -10,7 +10,7 @@
10
10
 
11
11
  ![Awesome DSH Plugin](https://awesome-dsh-plugin.com/badge.svg)![DSH 适配](https://img.shields.io/badge/DSH-0.2.1--rc.2%20%E5%B7%B2%E9%AA%8C%E8%AF%81-4E9BF1)![downloads](https://badgen.net/npm/dt/@furongjun1999/dsh-memory?label=downloads&color=4E9BF1)![Protocol](https://img.shields.io/badge/Protocol-MCP-blue)![Node](https://img.shields.io/badge/Node-%3E%3D22.19-brightgreen)![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)
12
12
 
13
- **高性能 · 无幻觉 · 多智能体适用的长期记忆系统(v0.9.9)**
13
+ **高性能 · 无幻觉 · 多智能体适用的长期记忆系统(v0.9.14)**
14
14
 
15
15
  📖 **[第三方上手教程](https://znsvdekx.vibedrop.site/)** —— 《灵枢 dsh-memory 初学者上手研究报告》(由第三方独立编写,非本项目官方文档)
16
16
 
@@ -18,6 +18,9 @@
18
18
 
19
19
  **灵枢是一套可运行的长期记忆基础设施**——对话自动沉淀为纯文本 md 认知图,记什么、取什么、能不能写入全部由确定性规则裁决,全程可审计、结果可复现。它不训练模型,做的是**模型之外的那一整套**:记忆怎么存、取的时候依据什么、写错了怎么被发现、改过怎么留痕。任何支持 MCP 的 AI Agent 可直接挂载,不与任何单一 Agent 框架绑定。
20
20
 
21
+ > **装不起来 / 看到奇怪的告警?** 先看 [环境与已知问题](docs/ops/环境与已知问题.md)——
22
+ > DSH Desktop 的启动告警、体积与整目录耦合、异步落盘、以及五条「看起来像 bug 其实是契约」的设计取舍都在那里。
23
+
21
24
  ## ⚠️ 升级须知:工具名去掉 lingshu_ 前缀(0.9.9 起)
22
25
 
23
26
  | 版本 | 工具名 |
@@ -49,6 +52,20 @@
49
52
  开 ① 后注入的是独立块【灵枢身份锚点】:最多 3 条、单条 160 字符、整块 640 字符,
50
53
  不占「最近记忆」块的预算,且与其它注入面一样过不可信边界标记与脱敏。
51
54
 
55
+ ## ⏱️ 长会话提醒(每 10 个真实用户回合)
56
+
57
+ 插件会在长会话里提醒做间歇归档(工作纪律第 16 条)。计轮单位是**真实用户回合**(用户消息条数),
58
+ 不是模型请求次数——一次请求内部会触发多次 system-prompt 组装,按组装次数计会把"每 10 轮"退化成"每一步"。
59
+
60
+ | 配置 | 行为 |
61
+ |---|---|
62
+ | memory.turnReminder: 10(默认) | 每 10 个用户回合提醒一次,**只出现一步** |
63
+ | memory.turnReminder: N | 自定义间隔(1~100) |
64
+ | memory.turnReminder: false | 整条关闭 |
65
+
66
+ 提醒只在命中那一步注入、下一步即消失(接受两份快照的代价),不会常驻上下文,
67
+ 也不会因并行会话共用一个计数器而放大频率(无会话标识时不提醒)。
68
+
52
69
  ## ⚡ 三条命令上手
53
70
 
54
71
  ```bash
@@ -82,7 +99,7 @@ python -m md_cg.mcp_server # 直连自检:收到 initialize 应答
82
99
  ## ✨ 核心亮点
83
100
 
84
101
  - **🧠 不失忆**——落盘即长期留存,遗忘只能显式发起、不做静默淘汰;检索索引只是派生物,**原文即真源**
85
- - **⚡ 高性能**——Rust 检索内核(零第三方依赖)+ `--serve` 进程实例支撑多智能体并发。公开基准 [hive-memory-bench](https://github.com/FuRongJun-1999/hive-memory-bench) 六家同口径:**逐字保真 100% · 保地基 68.4% · 证据链 97.7–99.2% · 写入 0.011–0.019 秒(零 LLM,同表其余 75.7–658.5 秒)**
102
+ - **⚡ 高性能**——Rust 检索内核(零第三方依赖)+ `--serve` 进程实例支撑多智能体并发。公开基准 [hive-memory-bench](https://github.com/FuRongJun-1999/hive-memory-bench) 六家同口径:**逐字保真 100% · 保地基 68.4%/65.0% · 证据链 97–100% · 写入 0.013–0.020 秒(零 LLM,同表其余 75.7–658.5 秒)**
86
103
  - **🛡️ 无幻觉**——记什么、取什么、能不能写入全部由确定性规则裁决,不依赖 LLM 黑箱;写没写成功只看 `committed`,绝不假装通过
87
104
  - **🔌 多智能体适用**——同一份大脑 + 同一份纪律,接入 DSH · CodeBuddy · ZCode · Codex CLI · Claude Code,任何 MCP 宿主可直接挂载
88
105
  - **📊 可复现评测**——权威对照在独立公开基准 hive-memory-bench;另公开两个自建题池;**已有两份第三方独立验证**(七轮复评 + LoCoMo 独立复现,自报数字逐位一致)
@@ -101,7 +118,7 @@ python -m md_cg.mcp_server # 直连自检:收到 initialize 应答
101
118
  | 📜 **中文编译器** | [`compiler/`](compiler/) | **验证 · 审计** | 词法 → 语法 → 名实校验 → 白名单代码生成 → 验证终裁,五环确定性编译链 |
102
119
  | ⬢ **蜂巢并发引擎** | [`hive/`](hive/) | **自我改进** | worker 池原子领取 / 心跳 / 超时强杀 / 崩溃恢复,文件协议即接口,MCP 五工具接入 |
103
120
 
104
- > 五件套共享同一套 18 条工作纪律与记忆闭环(见[工程纪律](#-工程纪律与设计者视角可选复用));**只用记忆就只接大脑**,不必理解蜂群与编译器。**🧬 身体面**(世界模型七层/3D 场景/白箱生成/蜂窝神经网络/记忆可视化)已独立公开为 [**FuRongJun-1999/lingshu**](https://github.com/FuRongJun-1999/lingshu)(经 MCP 与本大脑组合)。
121
+ > 五件套共享同一套 19 条工作纪律与记忆闭环(见[工程纪律](#-工程纪律与设计者视角可选复用));**只用记忆就只接大脑**,不必理解蜂群与编译器。**🧬 身体面**(世界模型七层/3D 场景/白箱生成/蜂窝神经网络/记忆可视化)已独立公开为 [**FuRongJun-1999/lingshu**](https://github.com/FuRongJun-1999/lingshu)(经 MCP 与本大脑组合)。
105
122
 
106
123
  ## 🚫 它不是什么
107
124
 
@@ -142,7 +159,7 @@ DeepSeek Harness (cordis)
142
159
  | 去哪里 | 看什么 |
143
160
  |---|---|
144
161
  | [docs/ 目录索引](docs/README.md) | 六域快速索引 · 新文档归域规则 |
145
- | [安装与运维](docs/ops/README.md) | 安装前置 / 30+ 配置项 / 写入凭据 / 升级重启 / 排障 FAQ |
162
+ | [安装与运维](docs/ops/README.md) | 安装前置 / 30+ 配置项 / 写入凭据 / 升级重启 / [环境与已知问题](docs/ops/环境与已知问题.md)(宿主告警·体积·落盘·设计取舍) |
146
163
  | [评测总览](docs/eval/评测总览.md) | 六家横评 / 弱证据与证据防火墙 / 中英双语差距 / 公开数据集 / 七维标尺 / 第三方验证 |
147
164
  | [开发与编码约定](docs/dev/README.md) | 测试约定 / UTF-8 与 id 契约 / 开关矩阵 / Linux 双栈验证 |
148
165
  | [多 harness 接入](docs/mdcg/多harness接入.md) | 五端纪律注入差异 / 出货面 vs 源码树分界 |
@@ -1,8 +1,8 @@
1
- # 工作纪律(工作纪律_认知图条目_v1.1)· 18 条
1
+ # 工作纪律(工作纪律_认知图条目_v1.1)· 19 条
2
2
 
3
3
  > 本文件由 `scripts/render_discipline.py` 从真源
4
4
  > `docs/工作纪律_认知图条目_v1.1.json` 渲染生成,**请勿手改**;改真源后重跑渲染。
5
- > 真源指纹(SHA256 前16位):9486668b0dadac39
5
+ > 真源指纹(SHA256 前16位):aea28906043ba9a2
6
6
 
7
7
  ## 概述
8
8
 
@@ -204,7 +204,7 @@
204
204
 
205
205
  **版本**:v1.1 | **状态**:待校准(未对外发布)
206
206
 
207
- ### 附录:本仓 18 条纪律(语义 / 触发 / 动作 / 声明出口)
207
+ ### 附录:本仓 19 条纪律(语义 / 触发 / 动作 / 声明出口)
208
208
 
209
209
  1. **1.理论先行**
210
210
  - 触发:重要项目|长期任务
@@ -278,6 +278,10 @@
278
278
  - 触发:查找工作区文件|需要了解工作区结构|跨目录检索定位|长会话续接/上下文压缩后查找工作区文件
279
279
  - 动作:定位工作区文件→先读 WORKSPACE_INDEX.md(仓根)→有则按表中职责/关键入口直接定位→无则先 python scripts/workspace_index.py --write 生成再读→守卫报陈化先重生成→不以重复全盘浏览代替; 新增顶层目录/根级文件须在脚本 DIR_ROLES/ROOT_FILES 登记后重生成; 上下文压缩/长会话续接后, 先 cg route『工作区索引』重建纪律视野(压缩会丢弃未留下执行痕迹的纪律, 只剩被声明过的条目——须主动召回); 压缩/续接后三步=route『工作区索引』→输出声明→回取本会话近10轮窗口重建上下文(cg(op=recent)/session_recall/会话 md 镜像)
280
280
  - 声明:按工作纪律第18条: 工作区索引优先——查工作区文件先读 WORKSPACE_INDEX.md(仓根, 管线生成); 无则先跑 scripts/workspace_index.py --write 生成再读, 不以重复全盘浏览代替。 压缩续接后并回取本会话窗口(最近10轮)重建上下文。
281
+ 19. **19.输出单元细则(echo三问/D_out/版本锚)**
282
+ - 触发:对外交付|对外材料/公开文档|回答外部提问|发版说明|对外数据集产出
283
+ - 动作:对外交付前→①按三问写 echo 页(<=200 字, 第二问必须指认判据 id/测试名/读数) ②补版本锚三元(理论/架构/本投影) ③跑 python scripts/gate_output.py 判绿 ④附当期 D_out 读数(首次允许很差, 但必须留基线)→任一不满足不得对外; 改口径先改真源再重渲染, 不得手改产物; 材料与实现版本不一致时以版本锚为准, 先修锚再发
284
+ - 声明:按工作纪律第19条: 输出单元细则——对外交付先写 echo 三问页(<=200字, 第二问须指认判据/断言id/读数)、带版本锚三元、跑 gate_output 并留当期 D_out 读数; 缺一不对外, 不做说服率/好感度测量。
281
285
 
282
286
  ## 声明出口(`response.direct` 原文 · 未输出即未执行)
283
287
 
@@ -301,6 +305,7 @@
301
305
  | 16 | 按工作纪律第16条: 任务收尾归档——每次任务执行完只提炼核心修改(内容/原因/位置/验证结论)并按 CCG 六要素(功能名/生效条件/子功能/执行/验证方式/不适用条件)成文存入灵枢记忆(text 类六要素缺失会被写入闸门当场拒绝并返回缺失清单——补齐后重写即可, 不必等读回确认才发现), 写入后发起一次读取查询确认写入成功且可检索, 禁写中间过程/试错/调试等无效信息, 与第2条形成「查记忆→执行→写记忆→读回确认」闭环。 |
302
306
  | 17 | 按工作纪律第17条: 任务派发统一走蜂巢——任何执行性任务经蜂巢 spawn/submit 执行并留痕(spec/status/result), agent本体只做编排; 宿主自带subagent/team不是等价通道(zcode端的工作流工具为等效蜂巢工具——使用者2026-10-04裁定; 蜂巢功能完全完善之前, zcode端可优先使用zcode工作流处理), 兜底须声明。L1只读判定(产物落点=不改仓库/外部状态)可直跑, 须输出「L1 直跑:<命令> — 风险/频次/可逆性」留痕。 |
303
307
  | 18 | 按工作纪律第18条: 工作区索引优先——查工作区文件先读 WORKSPACE_INDEX.md(仓根, 管线生成); 无则先跑 scripts/workspace_index.py --write 生成再读, 不以重复全盘浏览代替。 压缩续接后并回取本会话窗口(最近10轮)重建上下文。 |
308
+ | 19 | 按工作纪律第19条: 输出单元细则——对外交付先写 echo 三问页(<=200字, 第二问须指认判据/断言id/读数)、带版本锚三元、跑 gate_output 并留当期 D_out 读数; 缺一不对外, 不做说服率/好感度测量。 |
304
309
 
305
310
  ## 记忆接口速查(`cg` / `stg`)
306
311
 
@@ -1,92 +1,92 @@
1
- # CodeBuddy 端 · 灵枢接入配置
2
-
3
- 本目录 = **CodeBuddy harness 专属配置**(灵枢 = Lingshu 记忆系统)。与 `dsh/`、`zcode/` 平级,
4
- 共享层(`md_cg/` 大脑、`data/`、`docs/`、`scripts/`)在仓库根,不属任何单端。
5
-
6
- ## 目录内容
7
-
8
- | 文件 | 作用 | 性质 |
9
- |---|---|---|
10
- | `CODEBUDDY.md` | 18 条工作纪律全文(会话起始注入) | **渲染产物**,勿手改 |
11
- | `mcp.json` | 灵枢接入模板:`mdcg`(记忆大脑)+ `hive`(蜂巢并发)两条 MCP server(复制进 CodeBuddy 设置) | 模板 |
12
- | `README.md` | 本文件(接入说明 + 记忆策略) | 手写 |
13
-
14
- ## 三步接入
15
-
16
- ### 1. 接入记忆大脑(MCP)
17
-
18
- 把 `mcp.json` 里的 `mcpServers.mdcg` 一段合并进 CodeBuddy 的 MCP 配置,然后把
19
- `PYTHONPATH` 的占位值(`REPLACE_WITH_ABSOLUTE_PATH_TO_dsh-memory`)替换为**你本机
20
- dsh-memory 仓库所在目录**。此处须用可解析的绝对路径——Python 要据此定位仓库内的 `md_cg`
21
- 包,相对路径会随进程工作目录漂移而失效。
22
-
23
- `md_cg` 大脑随仓库自带,**无需 pip 安装任何引擎**;只需本机有 Python 与 Node ≥ 22.19。
24
-
25
- > **工具面 `MDCG_MCP_SURFACE=kernel`**(与 `md_cg/mcp_server.py` 的默认值一致):只暴露 `cg` /
26
- > `stg` 两个认知基元;`cg` 已覆盖 `route` / `read` / `write` 等全部 op,**写入通道不缺**。
27
- > 细粒度 `mdcg_*` 工具仅在 `full` 面可见,属兼容 / 调试用途,日常接入无需开启。
28
-
29
- #### 1b. 接入蜂巢(多智能体并发 + 任务上下文管理)
30
-
31
- `mcp.json` 里同源的第二条 `mcpServers.hive` 一并合并——四工具 `hive_spawn` / `hive_poll` /
32
- `hive_kill` / `hive_doctor`,提供**跨 harness 通用的并发执行**与**任务上下文管理**
33
- (`context_files` 注入、预算交回续跑、进展卡观察)。语义与边界见
34
- [`../hive/README.md`](../hive/README.md) 的「各 harness 注册」。
35
-
36
- > 依赖 Rust 侧 `hive.exe` 与 `hive/config.local.json`(执行器密钥)。未构建时先
37
- > `cd hive && cargo build --release`;`cargo` 不在 PATH 时改用绝对路径
38
- > `"%USERPROFILE%\.cargo\bin\cargo.exe" build --release --manifest-path hive/Cargo.toml`;
39
- > 首次 `hive_spawn` 会自动以 detached 方式拉起 `serve`。
40
- > **确定性任务(跑命令 / 测试)不在 MCP 面**,走 CLI:
41
- > `hive/target/release/hive.exe submit --spec <spec.json>`。
42
-
43
- ### 2. 注入工作纪律
44
-
45
- 把 `CODEBUDDY.md` 复制到**你项目的根目录**。
46
-
47
- > CodeBuddy 规则优先级:根目录存在 `CODEBUDDY.md` 时会**忽略 `AGENTS.md`**。
48
- > 本仓库刻意把产物放在 `codebuddy/` 子目录而**不落根**——因为仓库根的 `AGENTS.md`
49
- > 是本地私有载体(含本机运维注记,已被 `.gitignore` 忽略)。子目录放置既让外部用户可直接取用,
50
- > 又不屏蔽本地纪律。
51
-
52
- ### 3. 重启会话
53
-
54
- 纪律在**会话开始时全文注入一次**,改动后须新建会话才生效。
55
-
56
- ## 记忆策略:只记重要内容,不记流水
57
-
58
- 灵枢是记忆系统,但**什么都记等于什么都不记**——因此写入侧有两道机制化过滤,而非靠人自觉:
59
-
60
- | 层 | 内容 | 落点 | 过滤方式 |
61
- |---|---|---|---|
62
- | **重要内容** | 核心修改:内容 / 原因 / 位置 / 验证结论 | `knowledge` / `self` 层 | `cg(op=write, gated=true)` 过**三问四态闸门**,非 `ACCEPT` 不落盘 |
63
- | **对话记录** | 会话转录 | `contextual` 层 | 主动遗忘闸门按重要性阈值自动 `DROP` 低熵噪音 |
64
-
65
- - **纪律第 16 条**要求每次任务收尾主动归档核心修改——这是「对话 → 长期记忆」的闭环入口。
66
- - **严禁**写入中间过程 / 试错步骤 / 调试细节 / 重复确认;这类内容会污染检索、干扰后续召回。
67
- - CodeBuddy 侧**没有** DSH 那样的会话 hook 自动记忆,故记忆沉淀由纪律驱动(Agent 在收尾显式调用
68
- `cg(op=write, gated=true)`),而非进程自动抓取。
69
-
70
- ## 写入凭据(决定能否真正落盘)
71
-
72
- `md_cg` 是 **fail-closed**:不配凭据时插件以**只读 guest** 运行——读取 / 召回 / 时间线照常,
73
- 但记忆写入**不落盘**。要落盘请签发令牌:
74
-
75
- ```bash
76
- python -m md_cg.tokens issue --role designer --actor codebuddy --clearance internal ^
77
- --ops-allow info,route,read,write,recent,goal,identity,whitebox,verify ^
78
- --layers-allow knowledge,contextual,structural,self,goals,unresolved,rejected
79
- ```
80
-
81
- 然后把 `MDCG_TOKEN` 填进 `mcp.json` 的 `env`(或设系统环境变量后引用)。
82
-
83
- > **别把 `ok: true` 当写成功**:未落盘时返回体形如
84
- > `{"ok": true, "committed": false, "moved_to": "review_queue"}`——是否落盘**只看 `committed`**。
85
-
86
- ## 维护(面向灵枢维护者)
87
-
88
- - `CODEBUDDY.md` 由 `scripts/render_discipline.py` 从**唯一真源** `docs/工作纪律_认知图条目_v1.1.json`
89
- 渲染生成,矩阵见 `docs/discipline/harnesses.yaml`(`codebuddy` 槽位)。
90
- - 改纪律 → 改真源 → `python scripts/render_discipline.py --target codebuddy --write`
91
- → `python scripts/verify_discipline.py --target codebuddy` 通过 → 提交。
92
- - **手改本目录的 `CODEBUDDY.md` 会被 `verify_discipline.py` 判为漂移**。
1
+ # CodeBuddy 端 · 灵枢接入配置
2
+
3
+ 本目录 = **CodeBuddy harness 专属配置**(灵枢 = Lingshu 记忆系统)。与 `dsh/`、`zcode/` 平级,
4
+ 共享层(`md_cg/` 大脑、`data/`、`docs/`、`scripts/`)在仓库根,不属任何单端。
5
+
6
+ ## 目录内容
7
+
8
+ | 文件 | 作用 | 性质 |
9
+ |---|---|---|
10
+ | `CODEBUDDY.md` | 19 条工作纪律全文(会话起始注入) | **渲染产物**,勿手改 |
11
+ | `mcp.json` | 灵枢接入模板:`mdcg`(记忆大脑)+ `hive`(蜂巢并发)两条 MCP server(复制进 CodeBuddy 设置) | 模板 |
12
+ | `README.md` | 本文件(接入说明 + 记忆策略) | 手写 |
13
+
14
+ ## 三步接入
15
+
16
+ ### 1. 接入记忆大脑(MCP)
17
+
18
+ 把 `mcp.json` 里的 `mcpServers.mdcg` 一段合并进 CodeBuddy 的 MCP 配置,然后把
19
+ `PYTHONPATH` 的占位值(`REPLACE_WITH_ABSOLUTE_PATH_TO_dsh-memory`)替换为**你本机
20
+ dsh-memory 仓库所在目录**。此处须用可解析的绝对路径——Python 要据此定位仓库内的 `md_cg`
21
+ 包,相对路径会随进程工作目录漂移而失效。
22
+
23
+ `md_cg` 大脑随仓库自带,**无需 pip 安装任何引擎**;只需本机有 Python 与 Node ≥ 22.19。
24
+
25
+ > **工具面 `MDCG_MCP_SURFACE=kernel`**(与 `md_cg/mcp_server.py` 的默认值一致):只暴露 `cg` /
26
+ > `stg` 两个认知基元;`cg` 已覆盖 `route` / `read` / `write` 等全部 op,**写入通道不缺**。
27
+ > 细粒度 `mdcg_*` 工具仅在 `full` 面可见,属兼容 / 调试用途,日常接入无需开启。
28
+
29
+ #### 1b. 接入蜂巢(多智能体并发 + 任务上下文管理)
30
+
31
+ `mcp.json` 里同源的第二条 `mcpServers.hive` 一并合并——四工具 `hive_spawn` / `hive_poll` /
32
+ `hive_kill` / `hive_doctor`,提供**跨 harness 通用的并发执行**与**任务上下文管理**
33
+ (`context_files` 注入、预算交回续跑、进展卡观察)。语义与边界见
34
+ [`../hive/README.md`](../hive/README.md) 的「各 harness 注册」。
35
+
36
+ > 依赖 Rust 侧 `hive.exe` 与 `hive/config.local.json`(执行器密钥)。未构建时先
37
+ > `cd hive && cargo build --release`;`cargo` 不在 PATH 时改用绝对路径
38
+ > `"%USERPROFILE%\.cargo\bin\cargo.exe" build --release --manifest-path hive/Cargo.toml`;
39
+ > 首次 `hive_spawn` 会自动以 detached 方式拉起 `serve`。
40
+ > **确定性任务(跑命令 / 测试)不在 MCP 面**,走 CLI:
41
+ > `hive/target/release/hive.exe submit --spec <spec.json>`。
42
+
43
+ ### 2. 注入工作纪律
44
+
45
+ 把 `CODEBUDDY.md` 复制到**你项目的根目录**。
46
+
47
+ > CodeBuddy 规则优先级:根目录存在 `CODEBUDDY.md` 时会**忽略 `AGENTS.md`**。
48
+ > 本仓库刻意把产物放在 `codebuddy/` 子目录而**不落根**——因为仓库根的 `AGENTS.md`
49
+ > 是本地私有载体(含本机运维注记,已被 `.gitignore` 忽略)。子目录放置既让外部用户可直接取用,
50
+ > 又不屏蔽本地纪律。
51
+
52
+ ### 3. 重启会话
53
+
54
+ 纪律在**会话开始时全文注入一次**,改动后须新建会话才生效。
55
+
56
+ ## 记忆策略:只记重要内容,不记流水
57
+
58
+ 灵枢是记忆系统,但**什么都记等于什么都不记**——因此写入侧有两道机制化过滤,而非靠人自觉:
59
+
60
+ | 层 | 内容 | 落点 | 过滤方式 |
61
+ |---|---|---|---|
62
+ | **重要内容** | 核心修改:内容 / 原因 / 位置 / 验证结论 | `knowledge` / `self` 层 | `cg(op=write, gated=true)` 过**三问四态闸门**,非 `ACCEPT` 不落盘 |
63
+ | **对话记录** | 会话转录 | `contextual` 层 | 主动遗忘闸门按重要性阈值自动 `DROP` 低熵噪音 |
64
+
65
+ - **纪律第 16 条**要求每次任务收尾主动归档核心修改——这是「对话 → 长期记忆」的闭环入口。
66
+ - **严禁**写入中间过程 / 试错步骤 / 调试细节 / 重复确认;这类内容会污染检索、干扰后续召回。
67
+ - CodeBuddy 侧**没有** DSH 那样的会话 hook 自动记忆,故记忆沉淀由纪律驱动(Agent 在收尾显式调用
68
+ `cg(op=write, gated=true)`),而非进程自动抓取。
69
+
70
+ ## 写入凭据(决定能否真正落盘)
71
+
72
+ `md_cg` 是 **fail-closed**:不配凭据时插件以**只读 guest** 运行——读取 / 召回 / 时间线照常,
73
+ 但记忆写入**不落盘**。要落盘请签发令牌:
74
+
75
+ ```bash
76
+ python -m md_cg.tokens issue --role designer --actor codebuddy --clearance internal ^
77
+ --ops-allow info,route,read,write,recent,goal,identity,whitebox,verify ^
78
+ --layers-allow knowledge,contextual,structural,self,goals,unresolved,rejected
79
+ ```
80
+
81
+ 然后把 `MDCG_TOKEN` 填进 `mcp.json` 的 `env`(或设系统环境变量后引用)。
82
+
83
+ > **别把 `ok: true` 当写成功**:未落盘时返回体形如
84
+ > `{"ok": true, "committed": false, "moved_to": "review_queue"}`——是否落盘**只看 `committed`**。
85
+
86
+ ## 维护(面向灵枢维护者)
87
+
88
+ - `CODEBUDDY.md` 由 `scripts/render_discipline.py` 从**唯一真源** `docs/工作纪律_认知图条目_v1.1.json`
89
+ 渲染生成,矩阵见 `docs/discipline/harnesses.yaml`(`codebuddy` 槽位)。
90
+ - 改纪律 → 改真源 → `python scripts/render_discipline.py --target codebuddy --write`
91
+ → `python scripts/verify_discipline.py --target codebuddy` 通过 → 提交。
92
+ - **手改本目录的 `CODEBUDDY.md` 会被 `verify_discipline.py` 判为漂移**。
@@ -1,52 +1,52 @@
1
- # 全局指示(用户级 · 本机)
2
-
3
- > 本文件由 `scripts/render_discipline.py` 从真源
4
- > `docs/工作纪律_认知图条目_v1.1.json` 渲染生成(variant `zcode-user`),**请勿手改**;改真源后重跑渲染。
5
- > 真源指纹(SHA256 前16位):%%SOURCE_SHA%%
6
-
7
- ## 当工作目录是灵枢仓库(或其后代)时
8
-
9
- **会话起始第一件事——包含上下文压缩 / 长会话续接之后**:读该仓库的 `zcode/AGENTS.md`(18 条工作纪律 + 执行公约 + 声明出口表),并按其中的纪律执行。
10
-
11
- **压缩 / 续接后的上下文重建三步**:①读纪律文件(上句)→ ②输出命中纪律的 `response.direct` 原文 → ③**回取本会话近 10 轮窗口重建上下文**(`cg(op=recent)` 或 `session_recall`;会话 md 镜像只留最后 10 条、超长优先遗忘最旧,由会话钩子每轮交互后自动维护),然后才动手。
12
-
13
- **怎么认出灵枢仓库(机器无关的特征文件法)**:自当前工作目录向上找到第一个**并存**以下四者的目录,那里就是仓根——`utf8_boot.py`、`WORKSPACE_INDEX.md`、`docs/工作纪律_认知图条目_v1.1.json`、`zcode/AGENTS.md`(四者同时在场即本仓;只看 `AGENTS.md` 会误认——本仓纪律产物落在子目录 `zcode/`,仓根另有本地私有件)。
14
-
15
- 为什么需要这一步:`zcode/AGENTS.md` 位于仓库**子目录**,而 ZCode 的指令文件发现面是「用户级 `~/.zcode/AGENTS.md` + 工作区级 `<仓根>/AGENTS.md`,且工作区那份自 cwd **向上**搜到项目根」——向上搜索永远到不了子目录。因此它不会被自动注入;本文件(用户级)就是把它拉进上下文的那个钩子。
16
-
17
- 随后按纪律执行:
18
-
19
- - **0.1** 调 `cg(op=route, intent=<任务意图>)` 再动手,禁止跳过直接改码/跑命令。工具面若无 mdcg 工具,按第 7 条切等价兜底(进程内直调 `md_cg.mcp_server`)并声明降级,不得静默跳过。
20
- - **0.2** 命中纪律须在回复中输出该条 `response.direct` 原文(未声明即视为未执行)。**压缩只保留留下执行痕迹的条目——声明就是痕迹。**
21
- - **0.4 / 16** 违规即归档(第 4 条归因 + 第 16 条写入灵枢,六要素成文 + 读回确认);隐瞒违规是更严重的违规。
22
- - **16(长会话节奏)** 每完成 10 轮交互做一次间歇归档(同款写入 + 读回确认一次),不等收尾;逢十轮由会话钩子自动提醒。
23
- - **8** 中文思考
24
- - **触发**:中文区域|中文项目开发过程
25
- - **动作**:判定复杂度(情绪: 新奇/挑战/曾受批评 + 信息差: 不确定度)→复杂?「我们需要」深思考+确认 | 简单?「让我」快速执行; 推理开篇即中文锚点; 全程中文, 仅代码/标识符/引用保留原文
26
- - **不适用**:需要英文编写的场景|英文环境|英文文档|国际接口
27
- - **声明**:按工作纪律第8条: 中文思考——中文书写; 复杂(新奇/挑战/曾受批评/高信息差)→「我们需要」交流确认互补盲区; 简单→「让我」快速执行不空耗; 每段推理开篇用中文短语锚定语言。
28
- - **17** 改状态类任务派发蜂巢并留痕;只读判定(跑门禁/测试/回归看结论)可直跑,须输出一行「L1 直跑:<命令> — 风险/频次/可逆性」。
29
- - **18** 查工作区文件先读仓根 `WORKSPACE_INDEX.md`,不以重复全盘浏览代替;**压缩续接后回取本会话近 10 轮窗口重建上下文**(见上文三步)。
30
-
31
- 其它工作目录不受本段约束。
32
-
33
- ## 执行公约(0.1–0.5)
34
-
35
- | 约定 | 内容 |
36
- |---|---|
37
- | **0.1 会话起始先查记忆** | 动手前先调认知图入口——工具名随端:MCP 端 = server「mdcg」的 `cg`;DSH 端 = 内建基元 `cg`(即下文所有 `cg(...)`,同一服务勿因名字不同而猜测)。**`op` 是必填参数(route/read/write/verify/review…),任何调用都显式传、勿省略**。先 `cg(op=route, intent=<任务意图>)`;命中纪律/知识则按其 `execution.how` 执行。**禁止跳过此步直接改代码或跑命令。** |
38
- | **0.2 命中即声明** | 命中纪律须在回复中输出该条 `response.direct` 原文(「按工作纪律第 N 条:…」)。**这是「已执行」的唯一可观测证据;未声明即视为未执行。** |
39
- | **0.3 产出即证据** | 「动作」栏要求的产出(判定单/检索结果/验证结论/归档节点 id)必须实际给出,缺失即未执行。 |
40
- | **0.4 违规即归档** | 发现自己违反任一条 → 第 4 条归因 + 第 16 条写入灵枢记忆。**隐瞒违规本身是更严重的违规。** |
41
- | **0.5 例外不外溢** | 某条的「不适用」只豁免该条,不豁免其它条。 |
42
-
43
- ## 声明出口(`response.direct` 原文 · 未输出即未执行)
44
-
45
- %%DECLARATION_TABLE%%
46
-
47
- ---
48
-
49
- **机械守卫**(`python scripts/verify_discipline.py --target zcode-user`):
50
- 本件是**渲染产物**(variant `zcode-user`),不是手写件——手改表行 / 指纹 / 指向 / 任意正文,都会被守卫的「全文与重渲染逐字比对」判为漂移;
51
- 内嵌真源指纹(见文首)须等于当前真源 `docs/工作纪律_认知图条目_v1.1.json` 的指纹(判据侧按「陈化」硬失败);
52
- 仓外件缺失时 `--allow-missing` 跳过(裸 clone / CI 不误红),本机存在则须判绿。条款本体仍以 `<仓根>/zcode/AGENTS.md` 为准。
1
+ # 全局指示(用户级 · 本机)
2
+
3
+ > 本文件由 `scripts/render_discipline.py` 从真源
4
+ > `docs/工作纪律_认知图条目_v1.1.json` 渲染生成(variant `zcode-user`),**请勿手改**;改真源后重跑渲染。
5
+ > 真源指纹(SHA256 前16位):%%SOURCE_SHA%%
6
+
7
+ ## 当工作目录是灵枢仓库(或其后代)时
8
+
9
+ **会话起始第一件事——包含上下文压缩 / 长会话续接之后**:读该仓库的 `zcode/AGENTS.md`(19 条工作纪律 + 执行公约 + 声明出口表),并按其中的纪律执行。
10
+
11
+ **压缩 / 续接后的上下文重建三步**:①读纪律文件(上句)→ ②输出命中纪律的 `response.direct` 原文 → ③**回取本会话近 10 轮窗口重建上下文**(`cg(op=recent)` 或 `session_recall`;会话 md 镜像只留最后 10 条、超长优先遗忘最旧,由会话钩子每轮交互后自动维护),然后才动手。
12
+
13
+ **怎么认出灵枢仓库(机器无关的特征文件法)**:自当前工作目录向上找到第一个**并存**以下四者的目录,那里就是仓根——`utf8_boot.py`、`WORKSPACE_INDEX.md`、`docs/工作纪律_认知图条目_v1.1.json`、`zcode/AGENTS.md`(四者同时在场即本仓;只看 `AGENTS.md` 会误认——本仓纪律产物落在子目录 `zcode/`,仓根另有本地私有件)。
14
+
15
+ 为什么需要这一步:`zcode/AGENTS.md` 位于仓库**子目录**,而 ZCode 的指令文件发现面是「用户级 `~/.zcode/AGENTS.md` + 工作区级 `<仓根>/AGENTS.md`,且工作区那份自 cwd **向上**搜到项目根」——向上搜索永远到不了子目录。因此它不会被自动注入;本文件(用户级)就是把它拉进上下文的那个钩子。
16
+
17
+ 随后按纪律执行:
18
+
19
+ - **0.1** 调 `cg(op=route, intent=<任务意图>)` 再动手,禁止跳过直接改码/跑命令。工具面若无 mdcg 工具,按第 7 条切等价兜底(进程内直调 `md_cg.mcp_server`)并声明降级,不得静默跳过。
20
+ - **0.2** 命中纪律须在回复中输出该条 `response.direct` 原文(未声明即视为未执行)。**压缩只保留留下执行痕迹的条目——声明就是痕迹。**
21
+ - **0.4 / 16** 违规即归档(第 4 条归因 + 第 16 条写入灵枢,六要素成文 + 读回确认);隐瞒违规是更严重的违规。
22
+ - **16(长会话节奏)** 每完成 10 轮交互做一次间歇归档(同款写入 + 读回确认一次),不等收尾;逢十轮由会话钩子自动提醒。
23
+ - **8** 中文思考
24
+ - **触发**:中文区域|中文项目开发过程
25
+ - **动作**:判定复杂度(情绪: 新奇/挑战/曾受批评 + 信息差: 不确定度)→复杂?「我们需要」深思考+确认 | 简单?「让我」快速执行; 推理开篇即中文锚点; 全程中文, 仅代码/标识符/引用保留原文
26
+ - **不适用**:需要英文编写的场景|英文环境|英文文档|国际接口
27
+ - **声明**:按工作纪律第8条: 中文思考——中文书写; 复杂(新奇/挑战/曾受批评/高信息差)→「我们需要」交流确认互补盲区; 简单→「让我」快速执行不空耗; 每段推理开篇用中文短语锚定语言。
28
+ - **17** 改状态类任务派发蜂巢并留痕;只读判定(跑门禁/测试/回归看结论)可直跑,须输出一行「L1 直跑:<命令> — 风险/频次/可逆性」。
29
+ - **18** 查工作区文件先读仓根 `WORKSPACE_INDEX.md`,不以重复全盘浏览代替;**压缩续接后回取本会话近 10 轮窗口重建上下文**(见上文三步)。
30
+
31
+ 其它工作目录不受本段约束。
32
+
33
+ ## 执行公约(0.1–0.5)
34
+
35
+ | 约定 | 内容 |
36
+ |---|---|
37
+ | **0.1 会话起始先查记忆** | 动手前先调认知图入口——工具名随端:MCP 端 = server「mdcg」的 `cg`;DSH 端 = 内建基元 `cg`(即下文所有 `cg(...)`,同一服务勿因名字不同而猜测)。**`op` 是必填参数(route/read/write/verify/review…),任何调用都显式传、勿省略**。先 `cg(op=route, intent=<任务意图>)`;命中纪律/知识则按其 `execution.how` 执行。**禁止跳过此步直接改代码或跑命令。** |
38
+ | **0.2 命中即声明** | 命中纪律须在回复中输出该条 `response.direct` 原文(「按工作纪律第 N 条:…」)。**这是「已执行」的唯一可观测证据;未声明即视为未执行。** |
39
+ | **0.3 产出即证据** | 「动作」栏要求的产出(判定单/检索结果/验证结论/归档节点 id)必须实际给出,缺失即未执行。 |
40
+ | **0.4 违规即归档** | 发现自己违反任一条 → 第 4 条归因 + 第 16 条写入灵枢记忆。**隐瞒违规本身是更严重的违规。** |
41
+ | **0.5 例外不外溢** | 某条的「不适用」只豁免该条,不豁免其它条。 |
42
+
43
+ ## 声明出口(`response.direct` 原文 · 未输出即未执行)
44
+
45
+ %%DECLARATION_TABLE%%
46
+
47
+ ---
48
+
49
+ **机械守卫**(`python scripts/verify_discipline.py --target zcode-user`):
50
+ 本件是**渲染产物**(variant `zcode-user`),不是手写件——手改表行 / 指纹 / 指向 / 任意正文,都会被守卫的「全文与重渲染逐字比对」判为漂移;
51
+ 内嵌真源指纹(见文首)须等于当前真源 `docs/工作纪律_认知图条目_v1.1.json` 的指纹(判据侧按「陈化」硬失败);
52
+ 仓外件缺失时 `--allow-missing` 跳过(裸 clone / CI 不误红),本机存在则须判绿。条款本体仍以 `<仓根>/zcode/AGENTS.md` 为准。