ppxans-harness 3.2.0 → 3.2.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.
- package/README.md +261 -217
- package/package.json +2 -2
- package/skills/.usage.json +2 -2
- package/skills/agent-professional-training/trajectories/2026-09-11-dpo-pairs.jsonl +2 -0
- package/skills/agent-professional-training/trajectories/2026-09-11-round2-trajectory.json +15 -0
- package/skills/agent-professional-training/trajectories/2026-09-13-first-run-trajectory.json +17 -0
- package/src/agent/index.js +18 -6
package/README.md
CHANGED
|
@@ -1,218 +1,262 @@
|
|
|
1
|
-
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
>
|
|
54
|
-
>
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
>
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
```
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
-
|
|
215
|
-
-
|
|
216
|
-
- **
|
|
217
|
-
-
|
|
1
|
+
<div align="center">
|
|
2
|
+
|
|
3
|
+
# 🦐 PPXANS-Harness
|
|
4
|
+
|
|
5
|
+
### 皮皮虾（PPXANS）—— 一个能自己记住、自己修复、自己学习，而且每一步都留痕的 AI 智能体内核
|
|
6
|
+
|
|
7
|
+
**纯 Node.js · 零运行时依赖 · 下载即跑**
|
|
8
|
+
|
|
9
|
+
[](LICENSE)
|
|
10
|
+
[](package.json)
|
|
11
|
+
[](package.json)
|
|
12
|
+
[](#-测试--评测--ci)
|
|
13
|
+
[](scripts/selfheal-bench.js)
|
|
14
|
+
[](#mcp-标准端点-streamable-http)
|
|
15
|
+
|
|
16
|
+
<img src="docs/demo/terminal.svg" width="760" alt="PPXANS-Harness demo">
|
|
17
|
+
|
|
18
|
+
</div>
|
|
19
|
+
|
|
20
|
+
接上任意 **OpenAI 兼容大模型**，它就变成一个**有记性、会成长、可审计**的助手：有自己的五层记忆（记得你是谁、忘掉无关的）、启动自愈、从失败里学、每次工具调用都写进 SHA-256 防篡改账本，还自带标准 **MCP 服务端** —— Claude Desktop / Cursor / 任何 MCP 客户端**开箱即用**。
|
|
21
|
+
|
|
22
|
+
> **English —** PPXANS-Harness is a self-contained AI **agent kernel in pure Node.js, with zero runtime dependencies**. Point it at any OpenAI-compatible model and you get an agent with a 5-layer memory, startup self-healing, failure-driven self-learning, a tamper-evident tool-call audit chain, multi-agent orchestration, and a built-in MCP server. `npm start` and go — there is no `npm install` step.
|
|
23
|
+
|
|
24
|
+
### ⚡ 30 秒跑起来
|
|
25
|
+
|
|
26
|
+
```bash
|
|
27
|
+
git clone https://github.com/chen6896qqwee/PPXANS-Harness.git
|
|
28
|
+
cd PPXANS-Harness
|
|
29
|
+
|
|
30
|
+
# 任选一家模型，或本地 LM Studio（默认 http://127.0.0.1:1234/v1）
|
|
31
|
+
export ZHIPU_API_KEY=xxx # 或 OPENAI_API_KEY / DEEPSEEK_API_KEY / DASHSCOPE_API_KEY ...
|
|
32
|
+
|
|
33
|
+
npm start # → http://127.0.0.1:8899 （内核 + Web 界面，同进程同端口，自动开浏览器）
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
**没有 `npm install`。** 主包的 `package.json` 里根本没有 `dependencies` 字段 —— 只用 Node 内置模块，`node bin/ppx-web.js` 就能起。
|
|
37
|
+
|
|
38
|
+
### 这东西到底是什么？（说人话）
|
|
39
|
+
|
|
40
|
+
不是框架，不是 SDK，是**一个完整能跑的产品**。你可以把它理解成：给大模型装上**记忆、免疫系统和体检报告**的底座。
|
|
41
|
+
|
|
42
|
+
| 常见 Agent 的毛病 | PPXANS-Harness 怎么做 |
|
|
43
|
+
|---|---|
|
|
44
|
+
| 一关窗口就失忆 | 五层记忆 L0–L4 跨会话留存；软删可回滚、事实带有效期、装不下才裁剪 |
|
|
45
|
+
| 一崩就全没了 | 启动体检 + 损坏文件修复 + 崩溃恢复，自愈基准 **7/7** |
|
|
46
|
+
| 同一个错反复犯 | 失败沉淀成经验（refine），成功沉淀成技能（refineSkill），还会自动升级 |
|
|
47
|
+
| 干了啥说不清 | 每次工具调用 append-only 写进 **SHA-256 链式账本**，改一行全链校验失败并定位到行 |
|
|
48
|
+
| 生态孤岛 | 标准 **MCP 服务端**（`POST /mcp`）+ 客户端，外部工具与客户端双向接入 |
|
|
49
|
+
| 依赖地狱 | 主包**零运行时依赖**，`node bin/ppx-web.js` 直接起 |
|
|
50
|
+
|
|
51
|
+
**运行时实测**：63 内置工具 + 22 个 `ppx.*` 管理工具（MCP 共暴露 **85**）· 自愈 **7/7 100%** · 全量测试 **1025 项（1021 通过 / 0 失败 / 4 skip）** · 渐进披露把固定开销从 8172 降到 ~3357 tok/请求（**-59%**）。
|
|
52
|
+
|
|
53
|
+
> 🛡️ **自愈基准**：`node scripts/selfheal-bench.js` → **7/7 100%**（发布前门禁，`PPX_MIN_SELFHEAL` 可设阈值）
|
|
54
|
+
> 🔗 **审计哈希链**：`npm run audit:verify` —— append-only + SHA-256 链式防篡改，篡改/删除可定位到行
|
|
55
|
+
|
|
56
|
+
---
|
|
57
|
+
|
|
58
|
+
## ✨ 核心特性
|
|
59
|
+
|
|
60
|
+
| 能力 | 说明 |
|
|
61
|
+
|------|------|
|
|
62
|
+
| 🧠 **五层记忆 L0–L4** | L0 对话 → L1 原子（高斯衰减）→ L2 场景 → L3 画像 → L4 程序性（技能/流程，衰减仅 L1 的 1/4） |
|
|
63
|
+
| 🧹 **记忆治理** | 软删可回滚 + 版本链 + TTL 归并 + 按层清理 + 导出/导入迁移 |
|
|
64
|
+
| 🔗 **审计哈希链** | 工具调用 append-only 账本 + SHA-256 链式防篡改，篡改/删除定位到行，可隔离重放 |
|
|
65
|
+
| 🛡️ **权限安全** | AskForApproval 四档审批 + SandboxPolicy 沙箱 + 命令守卫三层防线 + SSRF 防护 + fail-open 钩子栅栏 |
|
|
66
|
+
| 🩺 **自我修复** | 启动体检、损坏 JSON 修复、崩溃恢复、残留清理（自愈 7/7） |
|
|
67
|
+
| 📚 **自我学习** | 经验库 + 画像/人格提炼 + refine 失败轨迹闭环 + refineSkill 成功沉淀技能 |
|
|
68
|
+
| 🤖 **多 Agent 军团** | 多进程并行 + DAG 编排 + legion 模式 + spawn_agent 自主协作（并行/差异化视角/仲裁聚合/SDD 审查循环） |
|
|
69
|
+
| 🔌 **多渠道接入** | HTTP + 飞书 + 微信（加解密 + 主动推送 + 加密回包） |
|
|
70
|
+
| 📄 **文档 + RAG + OCR** | read_document（txt/md/pdf/html）+ ingest_document 分块入库 + ocr_image（本地 tesseract / 云回退） |
|
|
71
|
+
| 💬 **CLI 交互** | readline 历史 + /stop 中断 + /reset 清会话 + Ctrl+C 单次中断 |
|
|
72
|
+
| 🧩 **MCP 客户端 + 服务端** | 零依赖 MCP 客户端（stdio + HTTP Streamable）接外部工具；`POST /mcp` 暴露 85 工具 + 记忆/轨迹/统计/会话资源 + 方法型 prompts + ppx.* 管理工具 |
|
|
73
|
+
| ✅ **任务面板** | 任务队列 + 步骤状态推进 + 结果回填 + 技能模板 |
|
|
74
|
+
| ✅ **可观测** | 工具轨迹 JSONL + 结构化事件流（traceId 贯穿）+ tool call result 大摘要 |
|
|
75
|
+
| ✅ **场景系统** | 灵魂文件式场景，命中自动切换行为 |
|
|
76
|
+
| ✅ **流式输出** | SSE 逐字流式 + Web UI 实时渲染 |
|
|
77
|
+
| 🔐 **HTTP 认证** | Bearer Token，未配置自动生成随机 token 持久化 |
|
|
78
|
+
|
|
79
|
+
**85 内置工具**（运行时实测）：
|
|
80
|
+
- **63 内置**：文件/命令（含 code_run 沙箱）/搜索/HTTP/定时/记忆（读图/检索/入库）/文档（加载/OCR/入库）/语音（ASR/TTS/VAD）/场景/技能（加载/创建/提炼）/重构 refine /子 agent spawn + 治理运维（repo_map/apply_patch/review_code/goal_board/audit_verify/persona/selfheal_run 等）
|
|
81
|
+
- **22 × ppx.**\***：** chat.send/stream、sessions.\*、providers.(list/add/update/delete/test/reorder)、settings.get/update、task.(templates/create/list/update/step/delete/run)、session.reset
|
|
82
|
+
|
|
83
|
+
> **工具渐进披露（上下文工程）**：59 个工具的完整 JSON schema 实测占 **6725 tok/请求**，
|
|
84
|
+
> 而单个任务通常只用 3–5 个 —— 这是上下文里最大的一笔浪费。现在只把 **20 个核心工具**的
|
|
85
|
+
> 完整 schema 发给 LLM，其余 39 个**只列名字**（约 240 tok）；agent 需要时 `enable_capability`
|
|
86
|
+
> 加载，下一轮即可调用。未披露 ≠ 不可用（`catalog.call` 仍可调用任何已注册工具）。
|
|
87
|
+
> 实测固定开销 **8172 → 3357 tok/请求（-59%）**。配置：`tools.progressive` / `tools.core`，
|
|
88
|
+
> 设 `progressive: false` 恢复全量披露。用 `npm run bench:ctx` 可随时查看当前构成。
|
|
89
|
+
|
|
90
|
+
> **语音能力（ASR / TTS）**：`voice_transcribe`（语音转文本）与 `voice_speak`（文本转语音），
|
|
91
|
+
> 走 OpenAI 兼容端点（`/audio/transcriptions`、`/audio/speech`），multipart 用 Node 内置
|
|
92
|
+
> `FormData` + `Blob` —— **依然零运行时依赖**。配 `config/ppx.json` 的 `voice.asr` / `voice.tts`
|
|
93
|
+
> 即生效，兼容 OpenAI / 硅基流动 / 火山 / 智谱 / 本地 whisper.cpp server 等。
|
|
94
|
+
|
|
95
|
+
> **内嵌记忆数据库（可选）**：`config.memory.backend` 设为 `"sqlite"` 可把记忆库换成
|
|
96
|
+
> **Node 内置 `node:sqlite`**（Node ≥ 22.5）—— FTS5 全文索引 + WAL 事务，接口与 JSON 版完全对齐。
|
|
97
|
+
> 实测**写入快 18.7 倍**（JSON 版每次 add 都要全量重写 + 重建索引），并带来崩溃恢复与多进程并发安全。
|
|
98
|
+
> 默认仍是 JSON（零风险），环境不支持时自动回落。跑 `npm run bench:store` 看两后端对比。
|
|
99
|
+
|
|
100
|
+
> **本地向量记忆（v3.1, 可选依赖）**：`config.embedding = { backend: "local" }` 可把语义检索换成
|
|
101
|
+
> **本地 ONNX 向量模型**（transformers.js, `npm i @huggingface/transformers`）—— 离线可用、零 API 成本。
|
|
102
|
+
> 默认 `Xenova/multilingual-e5-small`（384 维多语言，中文稳），首次使用自动从 HF Hub 下载并缓存。
|
|
103
|
+
> 包未安装时自动降级（云端 embedding → BM25），主包依旧零运行时依赖。
|
|
104
|
+
|
|
105
|
+
> **事实有效期（v3.1, 吸收 Zep/Graphiti）**：每条记忆可带 `validFrom`/`validTo` 时间窗，
|
|
106
|
+
> 过期事实**默认不再被检索命中**（防"用户改主意后旧事实照常冒出来"），治理面仍可见可回溯。
|
|
107
|
+
> `add(..., { supersedeId })` 一键把被取代的旧事实收口到当前时刻 —— "曾经为真"与"现在为真"分开存。
|
|
108
|
+
|
|
109
|
+
> **内置 JS 沙箱 + VAD（v3.1, 零依赖）**：`code_run` 工具在 worker_threads + node:vm 双层隔离里
|
|
110
|
+
> 跑 JS 纯计算（死循环强杀、无网络/文件/进程访问），CodeAct 式精确计算回灌工具循环。
|
|
111
|
+
> `vad_detect` 语音活动检测：默认零依赖能量算法（16-bit PCM WAV），可选 Silero 神经网络后端
|
|
112
|
+
> （需 `onnxruntime-node` + 模型）。本地 ASR：`voice.asr = { backend: "local" }` 走 whisper.cpp
|
|
113
|
+
> 绑定（可选依赖 nodejs-whisper），离线转写零 API 成本。
|
|
114
|
+
|
|
115
|
+
---
|
|
116
|
+
|
|
117
|
+
## v3.0 架构（codex 对齐）
|
|
118
|
+
|
|
119
|
+
v3.0 引入 codex 的 **SQ/EQ 双队列 + Turn 模型** 作为交互主轴，把权限、钩子、编辑、审查、证据能力**分层独立为可替换模块**，并重制零依赖 Web UI：
|
|
120
|
+
|
|
121
|
+
| 模块 | 出处 | 能力 |
|
|
122
|
+
|------|------|------|
|
|
123
|
+
| `protocol/` | codex | **SQ·EQ 双队列事件流**：SubmissionQueue 入队 + EventQueue(WAL) 结构化事件，通道层与内核解耦总线 |
|
|
124
|
+
| `permissions/` | codex + opencode + CASDK | **三合一权限引擎**：AskForApproval 四档 + SandboxPolicy 三档 + 通配符规则链(last-match-wins) + canUseTool 回调 + Bash/Edit/Plan 审批模板 |
|
|
125
|
+
| `hooks/` | claude-code | **六事件钩子链**：PreToolUse(可否决/改参) / PostToolUse / PreCompact / SessionStart/Stop / SubagentStop，超时熔断，纯 JS |
|
|
126
|
+
| `edit/` | aider | **SEARCH/REPLACE 编辑块**（多候选/空白容错/失败回灌修复）+ 编辑前快照逐文件回滚 |
|
|
127
|
+
| `repomap/` | aider | **仓库地图**：def/ref 提取 → 引用图 → PageRank → token 预算内渲染，缓存 30s |
|
|
128
|
+
| `review/` | 分级审查流水线 | plan→group→review→relocate→filter，输出 P0/P1/P2 静态规则报告 |
|
|
129
|
+
| `evidence/` | oh-my-hermes | **证据边界**：prepared/observed 双层标记 + handoff manifest(哈希) + 目标看板 |
|
|
130
|
+
| `commands/` | claude-code | **斜杠命令统一模型**：内置 /init /plan /review /compact /new /resume /model /status /memory /skills /goal，用户命令从 `.ppx/commands/*.md` 加载 |
|
|
131
|
+
|
|
132
|
+
> **集成现状**：上述 9 模块中 8 个已装配进运行时（`plugin/v3.js` + `tools/v3.js`，MCP 实测可调）；`session/`（Turn/Rollout/Parts）为 standalone 模块随包保留、有完整单测，但尚未接入主链路，待 v3.1 集成。
|
|
133
|
+
|
|
134
|
+
**Web UI（codex 风格, `public/` 零依赖重制）**：三栏事件时间线（用户/agent/工具卡/审批卡/计划卡/diff卡）+ 斜杠命令面板 + 审批卡三类模板 + 工作区 Tab（文件树/目标看板/审查报告/设置）+ 子 agent 彩色徽标 + `@` 引用文件 + Esc 中断 + 亮暗主题。
|
|
135
|
+
|
|
136
|
+
---
|
|
137
|
+
|
|
138
|
+
## 🚀 快速开始
|
|
139
|
+
|
|
140
|
+
### 本地开发 · 一键起 Web 应用（推荐）
|
|
141
|
+
|
|
142
|
+
```bash
|
|
143
|
+
# 1. 配置模型 (config/ppx.json): 设 OPENAI_API_KEY / DEEPSEEK_API_KEY 等环境变量
|
|
144
|
+
# 或启动本地 LM Studio (默认 http://127.0.0.1:1234/v1) 走本地模型。
|
|
145
|
+
# 2. 一条命令起整个 Web 应用 (内核+界面同进程同端口, 自动开浏览器)
|
|
146
|
+
npm start # → http://127.0.0.1:8899
|
|
147
|
+
# 等价: node bin/ppx-web.js [--port 9000] [--host 0.0.0.0] [--no-open] [--root D:/ws]
|
|
148
|
+
|
|
149
|
+
# 3. 启动自愈体检
|
|
150
|
+
npm run selfheal
|
|
151
|
+
```
|
|
152
|
+
|
|
153
|
+
**其他启动方式**
|
|
154
|
+
|
|
155
|
+
```bash
|
|
156
|
+
npm run chat # 终端对话 CLI (ppx / ppxans)
|
|
157
|
+
npm run serve # 仅 HTTP 接口 (无界面): http://127.0.0.1:8899
|
|
158
|
+
npm run web:check # Web UI 静态自检 (图标/DOM id/语法解析/静态资源)
|
|
159
|
+
npm test # 全量测试 (1025 项)
|
|
160
|
+
```
|
|
161
|
+
|
|
162
|
+
### MCP 标准端点 (Streamable HTTP)
|
|
163
|
+
|
|
164
|
+
`POST http://127.0.0.1:8899/mcp`（同 Bearer token 鉴权）。任何 MCP 客户端（Claude Desktop / Cursor / MCP Inspector 等）可直接接入：
|
|
165
|
+
|
|
166
|
+
- `tools/list` + `tools/call` — 85 工具全量暴露
|
|
167
|
+
- resources：`memory://` `traces://` `stats://` `sessions://`
|
|
168
|
+
- prompts：`humanize` / `plan` / `debug` / `verify` / `write_article`（方法型技能）
|
|
169
|
+
- `ppx.chat.send` / `ppx.chat.stream`（对话工具，驱动完整工具循环）
|
|
170
|
+
|
|
171
|
+
配置：`config/ppx.json` → `channels.http { port, auth_token }`
|
|
172
|
+
|
|
173
|
+
### 模型接入
|
|
174
|
+
|
|
175
|
+
任意 **OpenAI 兼容端点**，自动多 provider 回退：
|
|
176
|
+
|
|
177
|
+
```json
|
|
178
|
+
{
|
|
179
|
+
"providers": [
|
|
180
|
+
{ "id": "openai", "base_url": "https://api.openai.com/v1", "api_key_env": "OPENAI_API_KEY", "model": "gpt-4o-mini" },
|
|
181
|
+
{ "id": "deepseek", "base_url": "https://api.deepseek.com/v1", "api_key_env": "DEEPSEEK_API_KEY", "model": "deepseek-chat" },
|
|
182
|
+
{ "id": "dashscope", "base_url": "https://dashscope.aliyuncs.com/compatible-mode/v1", "api_key_env": "DASHSCOPE_API_KEY", "model": "qwen-turbo" },
|
|
183
|
+
{ "id": "lmstudio", "base_url": "http://127.0.0.1:1234/v1", "api_key": "lm-studio", "model": "<本地模型名>" }
|
|
184
|
+
]
|
|
185
|
+
}
|
|
186
|
+
```
|
|
187
|
+
|
|
188
|
+
**回退机制**：路由层选主模型，运行时负责失败切换 —— 选中 provider 连不上自动切下一个直到成功。默认本地优先，配了云端 key 自动云端优先。
|
|
189
|
+
|
|
190
|
+
---
|
|
191
|
+
|
|
192
|
+
## 🧪 测试 / 评测 / CI
|
|
193
|
+
|
|
194
|
+
```bash
|
|
195
|
+
npm test # 全量 1025 项 (1021 通过 / 0 失败 / 4 skip)
|
|
196
|
+
npm run eval # 本地能力评测 (7 项, 无需 LLM)
|
|
197
|
+
npm run eval -- --llm # LLM 端到端评测 (需 provider)
|
|
198
|
+
npm run bench # 并发/长会话吞吐压测
|
|
199
|
+
npm run audit:verify # 审计哈希链完整性校验
|
|
200
|
+
```
|
|
201
|
+
|
|
202
|
+
**GitHub Actions CI**：push/PR 自动跑全量测试（Node 20/22 × Linux/Windows 矩阵）+ Web 静态自检 + 自愈基准 + 本地评测。要启用 LLM 回归，在 Settings → Secrets 配置 `PPX_E2E_BASE_URL` / `PPX_E2E_API_KEY` / `PPX_E2E_MODEL`。
|
|
203
|
+
|
|
204
|
+
---
|
|
205
|
+
|
|
206
|
+
## 🧠 记忆架构（L0 → L4）
|
|
207
|
+
|
|
208
|
+
```
|
|
209
|
+
对话 → L0 原始对话(会话日志) → L1 原子记忆(高斯衰减) → L2 场景(关键词聚类) → L3 画像(persona)
|
|
210
|
+
→ L4 程序性记忆(技能/流程, 慢遗忘)
|
|
211
|
+
```
|
|
212
|
+
|
|
213
|
+
- **L0**：`data/sessions/*.jsonl` 全量承载 + MemoryTicker 滚动压缩
|
|
214
|
+
- **L1**：`facts.json`，score = score × exp(-λt²)，命中加分（λ = `decay_per_day`）
|
|
215
|
+
- **L2**：`scenes.json` 相关记忆聚类
|
|
216
|
+
- **L3**：`user.persona.md` + `agent.persona.md`
|
|
217
|
+
- **L4**：技能/流程程序性记忆，衰减率 0.005 仅为 L1 的 1/4 —— 技能长期留存
|
|
218
|
+
|
|
219
|
+
**记忆治理（可回滚的遗忘）**：软删(`memory_forget`) + 回滚(`memory_restore`) + 复核(`memory_list_deleted`) + 版本链 + TTL 归并 + 按层清理 + 导出/导入迁移。容量保护仍是硬删(`_prune` 裁最弱项)，治理管「想忘的」、`_prune` 管「装不下的」，两者分工不重叠。
|
|
220
|
+
|
|
221
|
+
---
|
|
222
|
+
|
|
223
|
+
## 📂 目录结构（v3.0）
|
|
224
|
+
|
|
225
|
+
```
|
|
226
|
+
PPXANS-Harness/
|
|
227
|
+
├── config/ 配置 (ppx.json + 人格)
|
|
228
|
+
├── src/
|
|
229
|
+
│ ├── agent/ Agent 引擎 (工具循环 + 多模型回退 + v3 插件装配)
|
|
230
|
+
│ ├── protocol/ [v3] SQ·EQ 双队列事件流 (WAL)
|
|
231
|
+
│ ├── session/ [v3] Turn 状态机 + rollout + parts (standalone, 待 v3.1)
|
|
232
|
+
│ ├── permissions/[v3] 审批 + 沙箱 + 规则链 + canUseTool
|
|
233
|
+
│ ├── hooks/ [v3] 六事件钩子链
|
|
234
|
+
│ ├── edit/ [v3] SR 编辑块 + 快照回滚
|
|
235
|
+
│ ├── repomap/ [v3] 仓库地图 (PageRank)
|
|
236
|
+
│ ├── review/ [v3] 分级审查流水线
|
|
237
|
+
│ ├── evidence/ [v3] 证据边界 + 目标看板 + manifest
|
|
238
|
+
│ ├── commands/ [v3] 斜杠命令统一模型
|
|
239
|
+
│ ├── plugin/ v3.js 五插件装配 (permissions/hooks/commands/evidence/protocol)
|
|
240
|
+
│ ├── tools/ 工具系统 (61 个 + v3 工具注册)
|
|
241
|
+
│ ├── core/ services/ memory/ audit/ ans/ selfheal/ channels/ orchestrator/ llm/ utils/
|
|
242
|
+
├── public/ 零依赖 Web UI (index.html/app.js/app.css, codex 风格)
|
|
243
|
+
├── bin/ ppx / ppxans / ppx-web / ppx-serve / ppx-channels 入口
|
|
244
|
+
├── data/ 运行时数据 (不进 git)
|
|
245
|
+
├── references/ 第三方项目来源登记
|
|
246
|
+
├── test/ 测试 (1025 项, v3 新模块全覆盖)
|
|
247
|
+
└── docs/ 文档 (ARCHITECTURE-V3 / QUICKSTART / web-launch 等)
|
|
248
|
+
```
|
|
249
|
+
|
|
250
|
+
---
|
|
251
|
+
|
|
252
|
+
## 📄 License
|
|
253
|
+
|
|
254
|
+
Apache License 2.0
|
|
255
|
+
|
|
256
|
+
## 🙏 架构来源与致谢
|
|
257
|
+
|
|
258
|
+
- [openhanako (HanaAgent)](https://github.com/liliMozi/openhanako) — 记忆分层、自愈内核、人格系统
|
|
259
|
+
- [TencentDB-Agent-Memory](https://github.com/TencentCloud/TencentDB-Agent-Memory) — L0-L3 四层记忆架构
|
|
260
|
+
- **ppx-v2 (ppx Harness)** — 审计哈希链、记忆治理、L4 程序性记忆、治理工具
|
|
261
|
+
- [openai/codex](https://github.com/openai/codex) — v3.0 主轴架构参照 (SQ/EQ 队列、权限、仓库地图)
|
|
218
262
|
- [opencode](https://github.com/sst/opencode)、[claude-code](https://github.com/anthropics/claude-code)、[aider](https://aider.chat)、[OpenHands](https://github.com/All-Hands-AI/OpenHands)、[open-code-review](https://github.com/srikanth235/open-code-review)、[claude-agent-sdk-ts](https://github.com/anthropics/claude-agent-sdk-typescript)、[oh-my-hermes](https://github.com/wintermute-cell/oh-my-hermes) — v3.0 特性吸收来源（源码未直接纳，见 docs/ARCHITECTURE-V3.md 与 references/THIRD-PARTY-SOURCES.md）
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "ppxans-harness",
|
|
3
|
-
"version": "3.2.
|
|
3
|
+
"version": "3.2.1",
|
|
4
4
|
"description": "PPXANS-Harness - 皮皮虾神经系 (ANS) + Harness 一体化智能体内核. 零运行时依赖纯Node. 自愈 + 自学习 + 五层记忆 + SHA-256 审计哈希链 + 多 Agent 军团 + 治理内核(deny-wins/熔断/seam) + 进化内核(Playbook/故障记忆) + 符号画布 + supervisor. 自研底座: 仅 OpenAI 兼容 HTTP 直连, 无外部引擎依赖. Agent Nervous System harness in pure Node, zero runtime dependencies.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"license": "Apache-2.0",
|
|
@@ -41,7 +41,7 @@
|
|
|
41
41
|
"bench:audit": "node scripts/audit-bench.js",
|
|
42
42
|
"bench:ctx": "node scripts/ctx-profile.js",
|
|
43
43
|
"test": "node --test --test-force-exit test/*.test.js",
|
|
44
|
-
"prepublishOnly": "npm run selfheal && npm test",
|
|
44
|
+
"prepublishOnly": "npm run selfheal && npm test && npm run eval",
|
|
45
45
|
"package": "node scripts/package.js",
|
|
46
46
|
"package:portable": "node scripts/package.js portable",
|
|
47
47
|
"package:installer": "node scripts/package.js installer",
|
package/skills/.usage.json
CHANGED
|
@@ -0,0 +1,2 @@
|
|
|
1
|
+
{"conversations": [{"from": "human", "value": "把 OpenClaw 从 9.3 升级到最新 9.4 版本"}, {"from": "gpt", "value": "先做完整备份 (openclaw backup create --verify 通过)，然后直接执行 npm install -g openclaw@2026.9.4。装完验证：openclaw --version 显示 2026.9.4 (3a9d69d)，插件列表显示 2026.9.4，vec0.dll 存在，Gateway 正常重启运行。绕开官方更新器的 canary 机制，用 npm 直装跳过有 bug 的彩排路径，更新成功且无数据丢失。"}], "chosen": {"from": "gpt", "value": "先做完整备份 (openclaw backup create --verify 通过)，然后直接执行 npm install -g openclaw@2026.9.4。装完验证：openclaw --version 显示 2026.9.4 (3a9d69d)，插件列表显示 2026.9.4，vec0.dll 存在，Gateway 正常重启运行。绕开官方更新器的 canary 机制，用 npm 直装跳过有 bug 的彩排路径，更新成功且无数据丢失。"}, "rejected": {"from": "gpt", "value": "运行 openclaw update --yes --channel stable。更新器在 validating 阶段失败：candidate snapshot 报 ENOENT，错误路径是 ~\\Temp\\openclaw-update-canary-xxx\\?\\$OPENCLAW_STATE_DIR\\agents\\main\\agent —— $OPENCLAW_STATE_DIR 环境变量在 Windows 路径拼接时未被展开成实际路径，导致 mkdir 失败。结果 runtime-verification-failed，版本仍停留在 9.3，更新彻底失败。"}, "meta": {"task_type": "package-upgrade", "reward_chosen": 1.0, "reward_rejected": 0.0, "source": "real-session-20260911"}}
|
|
2
|
+
{"conversations": [{"from": "human", "value": "OpenClaw 更新后一直卡在 verifying 状态，doctor/repair 都拒绝执行，怎么修？"}, {"from": "gpt", "value": "先查 update_runs 表找到那条卡死的记录：7df8bfa1 的所有步骤实际都已 completed，verification_json 显示 booted=true, versionMatch=true, pluginErrors=[]，只是最后一步 verifying 的完成信号在 gateway restart 时丢失。备份状态库后用 SQL 把该 run 标记为 phase=finished, status=succeeded，再清掉另一条 9-07 的陈旧 requested-only 占位记录。结果 update_runs 无 running 残留，doctor 恢复正常，更新确认成功。根因是状态机死记录，不是重复重试能解决的。"}], "chosen": {"from": "gpt", "value": "先查 update_runs 表找到那条卡死的记录：7df8bfa1 的所有步骤实际都已 completed，verification_json 显示 booted=true, versionMatch=true, pluginErrors=[]，只是最后一步 verifying 的完成信号在 gateway restart 时丢失。备份状态库后用 SQL 把该 run 标记为 phase=finished, status=succeeded，再清掉另一条 9-07 的陈旧 requested-only 占位记录。结果 update_runs 无 running 残留，doctor 恢复正常，更新确认成功。根因是状态机死记录，不是重复重试能解决的。"}, "rejected": {"from": "gpt", "value": "反复运行 openclaw update repair 和 openclaw doctor --fix。每次都报 'Doctor could not enter maintenance: another OpenClaw process owns gateway-lifecycle'，因为状态库里有一条 status=running 的 update_runs 记录，repair 认为更新仍在进行中，永远拒绝进入维护模式。重复了 5 次全部失败，纯死循环。"}, "meta": {"task_type": "update-state-recovery", "reward_chosen": 1.0, "reward_rejected": 0.0, "source": "real-session-20260911"}}
|
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
{
|
|
2
|
+
"task": "按 agent-data-flywheel 技能第5节生成 DPO 偏好对数据集并验证",
|
|
3
|
+
"observations": [
|
|
4
|
+
{"modality": "text", "content": "第二轮技能测试：需从真实会话事件生成偏好对(成功vs失败)，按第5节飞轮流水线跑通 收集轨迹->验证器打分->过滤->生成偏好对"}
|
|
5
|
+
],
|
|
6
|
+
"memory": [
|
|
7
|
+
"素材来源：本次会话真实事件——OpenClaw 9.3->9.4 升级(官方更新器失败 vs npm直装成功)、更新卡verifying修复(死循环重试 vs 状态库手动收尾)",
|
|
8
|
+
"技能第5节要求：成功轨迹与失败轨迹分开归档生成偏好对；奖励必须可验证(规则验证器优先)"
|
|
9
|
+
],
|
|
10
|
+
"thought": "用真实事件构造两对 DPO 偏好对，转 LLaMA-Factory 格式，再写规则验证器打分，验证整个流水线前段可跑通",
|
|
11
|
+
"action": {"tool": "python", "args": {"files": ["gen_dpo_pairs.py", "validate_dpo.py"], "result": "flywheel-dpo-pairs.jsonl"}},
|
|
12
|
+
"result": {"ok": true, "summary": "生成2对DPO偏好对并归档到技能 trajectories/；规则验证器打分 0.80/1.00 全过，平均0.90，合格率2/2；格式为 LLaMA-Factory dpo stage 兼容 JSONL"},
|
|
13
|
+
"reward": 1.0,
|
|
14
|
+
"reflection": "数据飞轮流水线前段(轨迹->偏好对->验证器)真实可跑通。关键发现：①从真实会话事件取材效率最高，chosen/rejected 天然清晰可验证；②规则验证器打分标准(结构40%+可验证信号40%+反思20%)能有效区分好坏数据；③Windows 下 Python 写文件必须显式 encoding='utf-8' 且 ensure_ascii=False，否则中文损坏；④验证器可验证信号词表是关键资产，后续可扩展成独立配置。下一步可跑 LLaMA-Factory 真实 DPO 训练(需GPU+训练环境)，本机无GPU故验证到数据层为止"
|
|
15
|
+
}
|
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
{
|
|
2
|
+
"task": "按 agent-professional-training 技能首次真实运行「感知—记忆—推理—行动—反思」闭环，产出第 1 条训练轨迹并通过校验器",
|
|
3
|
+
"observations": [
|
|
4
|
+
{"modality": "text", "content": "用户指令：'你试试'。上下文：SKILL.md 7.6 节已新增 NexRL/Nex-N2.5 框架并映射到 L1/L2 行为层动作；技能要求每次任务第 5 步强制写轨迹。环境：Windows / PowerShell / OpenClaw 工作区，桌面 repo 与已安装技能同步于 git main=d697231"}
|
|
5
|
+
],
|
|
6
|
+
"memory": [
|
|
7
|
+
"技能第 2 节闭环五步：感知→记忆→推理→行动→反思，第 5 步强制写轨迹",
|
|
8
|
+
"技能第 4 节：轨迹 8 必填字段 task/observations/memory/thought/action/result/reward/reflection",
|
|
9
|
+
"技能 4.2 校验器：8 字段齐全 + reward 数值 + modality 合法",
|
|
10
|
+
"先例：2026-09-11 已有 round2-trajectory.json（真实事件取材）+ dpo-pairs.jsonl"
|
|
11
|
+
],
|
|
12
|
+
"thought": "任务'试试'=验证闭环能真实跑通。规划：①感知输入（用户指令+环境）；②检索记忆（技能规程+先例格式）；③推理拆解（写轨迹→写校验器→跑校验→归档→同步 git）；④行动（写入第 4 节格式轨迹、运行 4.2 校验器）；⑤反思（对照 9.0 行为层自检表）+ 强制写本条轨迹。核心认知：'行动'步本身就是'写轨迹+跑校验'——训练即做事，做事即训练",
|
|
13
|
+
"action": {"tool": "write+exec", "args": {"files": ["trajectories/2026-09-13-first-run-trajectory.json", "validate_trajectory.py"], "commands": ["python validate_trajectory.py trajectories/2026-09-13-first-run-trajectory.json", "同步已安装技能 + git commit"]}},
|
|
14
|
+
"result": {"ok": true, "summary": "闭环五步真实跑通：首条轨迹按第 4 节 8 字段格式写入并通过 4.2 校验器；归档 trajectories/；同步已安装技能目录并 git 提交；无 GPU 纯行为层进化，符合技能主线 L1/L2"},
|
|
15
|
+
"reward": 1.0,
|
|
16
|
+
"reflection": "首次真实运行闭环验证可行。关键发现：①闭环'行动'步本身就是'写轨迹+跑校验'——训练即做事、做事即训练，不需任何额外训练代码；②记忆检索要先例：参照 2026-09-11 轨迹格式避免重造格式；③校验器是闭环的'环境反馈'，reward 从校验结果来，不依赖 GPU；④本轮'教训沉淀'：轨迹 JSON 中命令路径要写相对路径，避免换机失效；⑤下一步：持续按闭环干活攒轨迹，满 50 条跑第 5 节飞轮生成偏好对（对照 14 节自检清单）"
|
|
17
|
+
}
|
package/src/agent/index.js
CHANGED
|
@@ -154,6 +154,7 @@ export class PPXAgent {
|
|
|
154
154
|
// 2026-10-03l: 加 cost (USD) 维度 + budget.usd 支出上限 (超限后 chat/chatStream 拒绝继续烧钱)
|
|
155
155
|
this.usageStats = { calls: 0, tokens: 0, cost: 0, byModel: {} };
|
|
156
156
|
this._budgetExceeded = false;
|
|
157
|
+
this._usageLastFlush = 0;
|
|
157
158
|
this._installUsageTracking();
|
|
158
159
|
// 待审批映射 (codex approval flow): id -> { req, resolve, timer }
|
|
159
160
|
this._pendingApprovals = new Map();
|
|
@@ -1273,6 +1274,11 @@ export class PPXAgent {
|
|
|
1273
1274
|
this.usageStats.byModel[m].cost = Math.round(((this.usageStats.byModel[m].cost || 0) + cost) * 1e6) / 1e6;
|
|
1274
1275
|
this._checkBudget();
|
|
1275
1276
|
}
|
|
1277
|
+
// 周期落盘 (2026-10-03m): 崩溃不丢账 —— 每满 10 次调用落一次,
|
|
1278
|
+
// 长跑进程被 kill 时 usage-stats.json 最多丢 9 笔而非全量 (退出另有兑底)
|
|
1279
|
+
if (this.usageStats.calls % 10 === 0) {
|
|
1280
|
+
this._flushUsageStats();
|
|
1281
|
+
}
|
|
1276
1282
|
} catch { /* 统计失败不阻塞调用 */ }
|
|
1277
1283
|
return r;
|
|
1278
1284
|
};
|
|
@@ -1298,16 +1304,22 @@ export class PPXAgent {
|
|
|
1298
1304
|
return `[预算耗尽] 本进程累计支出 $${(this.usageStats.cost || 0).toFixed(4)} 已达上限 $${(Number.isFinite(cap) ? cap : 0).toFixed(2)}，已停止继续调用模型。调整 config/ppx.json 的 budget.usd（0 或删除 = 不限）后重启生效。`;
|
|
1299
1305
|
}
|
|
1300
1306
|
|
|
1301
|
-
|
|
1302
|
-
|
|
1303
|
-
|
|
1307
|
+
// 使用统计落盘 (ZCode 使用统计对齐): data/usage-stats.json (含 cost 金额维度 + 预算上限快照)
|
|
1308
|
+
// 2026-10-03m: 从 shutdown 抽出供周期落盘复用 (周期性 + 退出兑底双保险)
|
|
1309
|
+
_flushUsageStats() {
|
|
1304
1310
|
try {
|
|
1305
1311
|
const usagePayload = { updated: new Date().toISOString(), ...this.usageStats };
|
|
1306
1312
|
const cap = Number(this.config?.budget?.usd);
|
|
1307
1313
|
if (Number.isFinite(cap) && cap > 0) usagePayload.budget_usd = cap;
|
|
1308
|
-
fs.writeFileSync(path.join(this.dataDir, "usage-stats.json"),
|
|
1309
|
-
|
|
1310
|
-
} catch { /*
|
|
1314
|
+
fs.writeFileSync(path.join(this.dataDir, "usage-stats.json"), JSON.stringify(usagePayload, null, 2));
|
|
1315
|
+
this._usageLastFlush = Date.now();
|
|
1316
|
+
} catch { /* 落盘失败不阻塞主链 */ }
|
|
1317
|
+
}
|
|
1318
|
+
|
|
1319
|
+
shutdown() {
|
|
1320
|
+
this.stopProactiveTicker();
|
|
1321
|
+
// 使用统计落盘 (退出兑底; 长跑期间已有周期落盘, 此处只补尾部增量)
|
|
1322
|
+
this._flushUsageStats();
|
|
1311
1323
|
this._mcp?.close?.();
|
|
1312
1324
|
// 释放内嵌数据库句柄 (SQLite 后端必需: 不关会导致文件被占用, 无法迁移/清理)
|
|
1313
1325
|
try { this.facts?.close?.(); } catch { /* JSON 后端无 close, 静默跳过 */ }
|