dsh-superagent-ptc 0.1.3 → 0.1.5

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 CHANGED
@@ -1,5 +1,7 @@
1
1
  # SuperAgent PTC
2
2
 
3
+ **English** | [Chinese](README.zh-CN.md)
4
+
3
5
  [![npm version](https://img.shields.io/npm/v/dsh-superagent-ptc?color=cb3837)](https://www.npmjs.com/package/dsh-superagent-ptc)
4
6
  [![npm downloads](https://img.shields.io/npm/dm/dsh-superagent-ptc?color=blue)](https://www.npmjs.com/package/dsh-superagent-ptc)
5
7
  [![license MIT](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
@@ -7,235 +9,232 @@
7
9
  [![tests](https://img.shields.io/badge/tests-176%2F176-brightgreen)](docs/VALIDATION.md)
8
10
 
9
11
  > **Long-task supervision layer for DeepSeek Harness** — versioned anchors, bounded delegation, independent acceptance, evidence-gated release.
10
- > **DSH 长任务监督层** —— 目标锚点、有界委派、独立验收、证据放行。
11
12
 
12
13
  SuperAgent PTC turns "the agent says it is done" into "an independent reviewer proved it is done". It is a **preset-first** plugin: it adds a supervision plane on top of the native PTC / Agent / Goal / Teams runtime instead of building a second agent loop, task board or router.
13
14
 
14
15
  ```
15
- 你:把这份调研拆成三项工作,逐个验收后再写总结
16
- SuperAgent PTC:Run + Anchor → 逐项 Mandate 派给 Worker → standard Reviewer 独立核验
17
- → 证据通过才放行 → super_snapshot 给出可验证的 revision/proof
16
+ You: split this research into three items, accept each one, then write the summary
17
+ PTC: Run + Anchor -> Mandate per item -> standard Reviewer verifies independently
18
+ -> gate passes -> super_snapshot returns revision and proof
18
19
  ```
19
20
 
20
- ![Layered architecture](docs/images/architecture-layers.png)
21
+ ![Layered architecture](docs/images/en/architecture-layers.png)
21
22
 
22
- ## 目录
23
+ ## Contents
23
24
 
24
- - [为什么需要它](#为什么需要它)
25
- - [特性](#特性)
26
- - [双层架构](#双层架构)
27
- - [监督循环](#监督循环)
28
- - [安装](#安装)
29
- - [快速上手](#快速上手)
30
- - [工具一览](#工具一览)
31
- - [右栏监管面板](#右栏监管面板)
32
- - [证据门与安全边界](#证据门与安全边界)
33
- - [兼容性](#兼容性)
34
- - [验证](#验证)
35
- - [常见问题](#常见问题)
36
- - [开发与贡献](#开发与贡献)
37
- - [许可](#许可)
25
+ - [Why](#why-superagent-ptc)
26
+ - [Features](#features)
27
+ - [Dual-layer architecture](#dual-layer-architecture)
28
+ - [Supervision loop](#supervision-loop)
29
+ - [Install](#install)
30
+ - [Quick start](#quick-start)
31
+ - [Tools](#tools)
32
+ - [Right panel](#right-panel)
33
+ - [Evidence gates and boundaries](#evidence-gates-and-boundaries)
34
+ - [Compatibility](#compatibility)
35
+ - [Verification](#verification)
36
+ - [FAQ](#faq)
37
+ - [Development](#development)
38
+ - [Acknowledgements](#acknowledgements)
39
+ - [License](#license)
38
40
 
39
- ## 为什么需要它
41
+ ## Why SuperAgent PTC
40
42
 
41
- 长任务失败通常不是"模型不会",而是四件事没有被约束:
43
+ Long tasks rarely fail because the model cannot write code. They fail because four things stay unconstrained:
42
44
 
43
- | 常见问题 | 后果 | SuperAgent PTC 的做法 |
45
+ | Problem | Consequence | What SuperAgent PTC does |
44
46
  | --- | --- | --- |
45
- | 目标在长对话里漂移 | 做到一半换了题目 | **版本化 Anchor**:目标、DoD、义务都有版本,纠正会显式失效旧工作 |
46
- | Agent 自报完成 | "done" 但没有验证 | `reported_done ≠ accepted`,必须过独立 Reviewer 与证据门 |
47
- | 委派没有边界 | Worker 越权、重复劳动 | **Mandate 委派合同**:工作项、写域、模型路由、attempt 计数都冻结在合同里 |
48
- | 崩溃后状态不明 | 不知道做到哪,证据是否可信 | **SnapshotProof + RunState v2**:先写原生证明,再落存储,最后替换 live core |
47
+ | The goal drifts across a long conversation | Half the work targets the wrong thing | **Versioned Anchor**: objective, DoD and obligations have versions; corrections explicitly invalidate affected work |
48
+ | The agent declares itself done | "Done" without verification | `reported_done != accepted`: an independent Reviewer and an evidence gate must pass first |
49
+ | Delegation has no boundary | Workers overreach or duplicate effort | **Mandate contract**: work item, write scope, model route and attempt count are frozen at prepare time |
50
+ | Crash leaves an unknown state | You cannot tell what is trustworthy | **SnapshotProof + RunState v2**: write the native proof, then storage, then swap the live core |
49
51
 
50
- ## 特性
52
+ ## Features
51
53
 
52
- - **Preset-first**:与标准、创造、PTC、极简并列的一个 Agent 预设(`SuperAgent PTC`),不改默认模型、权限或其他会话。
53
- - **七项监管工具**:`super_run`、`super_anchor`、`super_mandate`、`super_evidence`、`super_review`、`super_route`、`super_snapshot`,全部通过 PTC 的 `run_code` 调用,不新增脚本工具。
54
- - **原生身份绑定**:Worker / Reviewer 是真实的原生子 Agent;Host 用原生 `sendMessage` 唤醒绑定的 Reviewer,杜绝"Lead 自己扮演 Reviewer"。
55
- - **独立只读验收**:Reviewer 必须是原生 `standard` 预设,guard 对它的写操作和未知 shell 分类 fail-closed;`pwsh` 只读命令(含 `$env:` 读取)按实际参数分类。
56
- - **分型证据门**:证据只有 `pass / fail / unknown` 三态;`unknown` 不放行;build/单测/截图不能替代 runtime 证据。
57
- - **失败预算与可恢复审计**:同 fingerprint 达上限即 blocked;`super_run recover` 增代并保留完整审计链。
58
- - **客户端可视化**:右栏监管面板 + composer 入口,只读投影,不写状态。
59
- - **零全局副作用**:普通会话没有 `super_*` 工具、没有提示词、没有面板。
54
+ - **Preset-first**: one agent preset (`SuperAgent PTC`) alongside Standard, Creative, PTC and Minimal; it does not change default models, permissions or other sessions.
55
+ - **Seven supervision tools**: `super_run`, `super_anchor`, `super_mandate`, `super_evidence`, `super_review`, `super_route`, `super_snapshot`, all called through PTC `run_code` instead of adding new script tools.
56
+ - **Native identity binding**: Worker and Reviewer are real native subagents; the Host wakes a bound Reviewer through native `sendMessage`, so the Lead can never play the Reviewer.
57
+ - **Independent read-only review**: the Reviewer must use the native `standard` preset; the guard fails closed on writes and unknown shell operations, while `pwsh` read commands (including `$env:` reads) are classified by their actual arguments.
58
+ - **Typed evidence gates**: evidence is `pass / fail / unknown` only; `unknown` never releases; build logs, unit tests and screenshots cannot replace runtime evidence.
59
+ - **Failure budgets and recoverable audit**: the same fingerprint reaching its budget blocks the run; `super_run recover` increases the generation and keeps the full audit trail.
60
+ - **Client visualization**: a right-side supervision panel and a composer entry over a read-only projection.
61
+ - **No global side effects**: ordinary sessions get no `super_*` tools, no prompt section and no panel.
60
62
 
61
- ### 一张表说清"它不做什么"
63
+ ### What it deliberately does not do
62
64
 
63
- | 不做 | 原因 |
65
+ | Not doing | Reason |
64
66
  | --- | --- |
65
- | 不重建 Agent loop / 任务板 / 全局路由 | 原生 Session、Agent、Goal、Teams 才是执行权威 |
66
- | 不提供全局文件权限沙箱 | 写域是协作契约,不是操作系统级隔离 |
67
- | 不做自动模型降级 | 只在显式授权、allowlist 与预算内的有界故障切换 |
68
- | 不把 `reported_done` 当验收 | 独立 Reviewer + 证据门才产生 `accepted` |
67
+ | Rebuilding an agent loop, task board or global router | Native Session, Agent, Goal and Teams remain the execution authority |
68
+ | Providing an OS-level file permission sandbox | Write scopes are a coordination contract, not kernel isolation |
69
+ | Automatic model downgrade | Only explicit, allowlisted, budgeted bounded failover is supported |
70
+ | Treating `reported_done` as acceptance | Only an independent Reviewer plus the evidence gate produces `accepted` |
69
71
 
70
- ## 双层架构
72
+ ## Dual-layer architecture
71
73
 
72
- **一句话定位**:SuperAgent PTC 在宿主原生 Agent/Session 机制之上叠加一层监管状态机(`Run → Anchor → Mandate → Evidence → Decision`),把原生 agent 会话按角色(Lead / Worker / Reviewer)绑定进这条监管链;**PTC 的原生事件链**(`run_code` 调用与工具回执)**是整条链的证据底座**——监管层自己不产生第二套事件流。
74
+ **One-sentence positioning**: SuperAgent PTC layers a supervision state machine (`Run -> Anchor -> Mandate -> Evidence -> Decision`) on top of the native Agent/Session mechanism, binds native agent sessions into that chain by role (Lead / Worker / Reviewer), and treats the **native PTC event chain** (`run_code` calls and tool receipts) as the **evidence substrate** of the whole chain. The supervision layer never produces a second event stream.
73
75
 
74
- 监管面(Control Plane)只回答"能不能放行",执行面(Execution Plane)只回答"实际做了什么",两者之间只有一条契约膜:`super_*` 工具是状态与证据的唯一写入口。
76
+ The supervision plane only answers "may this ship"; the execution plane only answers "what actually happened". Between them sits a single contract membrane: `super_*` tools are the only writer of state and evidence.
75
77
 
76
- ![Dual-layer architecture](docs/images/architecture-dual.png)
78
+ ![Dual-layer architecture](docs/images/en/architecture-dual.png)
77
79
 
78
- - **A 监督面**:Lead 维护 Anchor 与义务账本;Mandate 冻结工作项、写域、路由与 attempt;证据门与预算决定放行。
79
- - **契约膜**:任何状态变更都必须穿过 `super_*` 的 CAS 校验,双层之间没有第二套写路径。
80
- - **B 执行面**:PTC `run_code` 编排宿主工具、原生 `subagent` 创建 Worker/Reviewer,回执以 `reported_done` 与工具结果的形式返回。
81
- - **共同底座**:原生运行时提供身份、生命周期与证明;`storageDomain RunState v2` 与 `SnapshotProof` 保证崩溃后可恢复。
80
+ - **A Supervision plane**: the Lead maintains the Anchor and the obligation ledger; a Mandate freezes work item, write scope, route and attempt; evidence gates and budgets decide release.
81
+ - **Contract membrane**: every state change must pass the `super_*` CAS check; there is no second write path between the planes.
82
+ - **B Execution plane**: PTC `run_code` orchestrates host tools, native `subagent` creates Worker and Reviewer, and receipts come back as `reported_done` plus tool results.
83
+ - **Shared foundation**: the native runtime supplies identity, lifecycle and proof; `storageDomain RunState v2` and `SnapshotProof` make the run recoverable.
82
84
 
83
- ## 监督循环
85
+ ## Supervision loop
84
86
 
85
- ![Supervision loop](docs/images/lifecycle.png)
87
+ ![Supervision loop](docs/images/en/lifecycle.png)
86
88
 
87
89
  ```text
88
- super_run create # 目标 + 完成定义 + 门禁策略
89
- super_run plan # 工作项 / 依赖 / 义务(开放账本)
90
- super_anchor # 版本化锚点;纠正时显式失效受影响工作
91
- super_mandate prepare # 冻结工作项、写域、模型路由、attempt
92
- super_mandate bind # 绑定原生 Worker SessionId
93
- super_mandate bindReviewer # 绑定 standard Reviewer,Host 原生唤醒
94
- super_evidence record # 证据三态,必须可追溯
95
- super_review evaluate # 门禁评估
96
- super_review decide/release # 通过才放行
97
- super_snapshot # 只读核对 revision / generation / proof
90
+ super_run create # objective + definition of done + gate policy
91
+ super_run plan # work items / dependencies / obligations (open ledger)
92
+ super_anchor # versioned anchor; corrections invalidate affected work
93
+ super_mandate prepare # freeze work item, write scope, model route, attempt
94
+ super_mandate bind # bind the native Worker SessionId
95
+ super_mandate bindReviewer # bind a standard Reviewer and wake it natively
96
+ super_evidence record # typed, traceable evidence
97
+ super_review evaluate # gate evaluation
98
+ super_review decide/release # release only when the gate passes
99
+ super_snapshot # read-only check of revision / generation / proof
98
100
  ```
99
101
 
100
- ## 安装
102
+ ## Install
101
103
 
102
- 要求:DSH `>=0.2.2-rc.3 <0.3.0-0`,Node `^22.19.0 || >=24`。
104
+ Requires DSH `>=0.2.2-rc.3 <0.3.0-0` and Node `^22.19.0 || >=24`.
103
105
 
104
106
  ```bash
105
- # npm 安装到当前 profile
107
+ # install from npm into the current profile
106
108
  dsh plugin --profile desktop add dsh-superagent-ptc
107
-
108
- # 或使用完整包名说明(等价)
109
- dsh plugin --profile desktop add npm:dsh-superagent-ptc
110
109
  ```
111
110
 
112
- 安装后**完全退出并重新启动 DSH**,然后新建会话,在预设选择器里选择 **SuperAgent PTC**。
111
+ Restart DSH completely after installing, then create a session and pick **SuperAgent PTC** in the preset selector.
113
112
 
114
- ### 通过 DSH 插件市场索引安装
113
+ ### Install through the DSH plugin market index
115
114
 
116
- 在 DSH → 设置 → 插件 → 发现 中添加索引 URL,然后搜索 `SuperAgent PTC`:
115
+ In DSH -> Settings -> Plugins -> Discover, add this index URL and search for `SuperAgent PTC`:
117
116
 
118
117
  ```text
119
118
  https://raw.githubusercontent.com/BioAIEvolu/dsh-superagent-ptc/main/market-index.json
120
119
  ```
121
120
 
122
- 该索引已通过 DSH 官方 `parseMarketIndex` 校验,安装规格为 `dsh-superagent-ptc@0.1.0`。
121
+ The index passes the official `parseMarketIndex` validation and resolves to `dsh-superagent-ptc@0.1.3`.
123
122
 
124
- 想先本地试用?把仓库 clone 下来用 `link:` 安装:
123
+ ### Local development install
125
124
 
126
125
  ```bash
127
126
  git clone https://github.com/BioAIEvolu/dsh-superagent-ptc.git
128
127
  dsh plugin --profile desktop add link:/absolute/path/to/dsh-superagent-ptc
129
128
  ```
130
129
 
131
- ## 快速上手
130
+ ## Quick start
132
131
 
133
- 1. 新建会话,选择 **SuperAgent PTC** 预设。
134
- 2. 直接说清目标与完成标准,例如:
132
+ 1. Create a session and choose the **SuperAgent PTC** preset.
133
+ 2. Describe the objective and the definition of done, for example:
135
134
 
136
135
  ```text
137
- 用 SuperAgent PTC 做最小监管闭环:
138
- super_run create 建 Run;plan 两个工作项,W1 读 README 并给 3 条要点,W2 依赖 W1 本阶段保持 held;
139
- Worker 继承 super-agent,Reviewer 用 agent_preset=standard;
140
- prepare/bind/bindReviewer 后由 Reviewer 独立记录 coverage 证据并 evaluate/decide/release;
141
- 最后 super_snapshot 报告真实 Run/WorkItem/Mandate/Evidence/Decision ID 与 revision/generation/proof。
136
+ Use SuperAgent PTC for a minimal supervision loop:
137
+ super_run create a Run; plan two work items, W1 reads the README and lists 3 points, W2 depends on W1 and stays held this phase;
138
+ let the Worker inherit super-agent and the Reviewer use agent_preset=standard;
139
+ after prepare/bind/bindReviewer, the Reviewer records coverage evidence and runs evaluate/decide/release;
140
+ finally call super_snapshot and report the real Run/WorkItem/Mandate/Evidence/Decision IDs plus revision/generation/proof.
142
141
  ```
143
142
 
144
- 3. 点击 composer 上方的 **Super Agent 监管**,右栏会显示真实 Run 状态与审计时间线。
143
+ 3. Click **Super Agent supervision** above the composer; the right panel shows the live run and audit timeline.
145
144
 
146
- ## 工具一览
145
+ ## Tools
147
146
 
148
- | 工具 | 关键动作 | 说明 |
147
+ | Tool | Actions | Notes |
149
148
  | --- | --- | --- |
150
- | `super_run` | `create` `plan` `show` `recover` `complete` | Run 生命周期;`recover` 增代并重新对账 |
151
- | `super_anchor` | `show` `apply` `history` | 版本化锚点;纠正时显式失效受影响工作 |
152
- | `super_mandate` | `prepare` `bind` `bindReviewer` `report` `show` | 委派合同与原生 SessionId 绑定 |
153
- | `super_evidence` | `record` `observe` `list` | 证据三态,写域与来源角色校验 |
154
- | `super_review` | `evaluate` `decide` `release` | 独立验收与放行 |
155
- | `super_route` | `show` `set` `inspect` `switch` | 当前 Run 的模型策略与有界切换 |
156
- | `super_snapshot` | `{}` | 只读核对 Run / gate / proof / recovery |
149
+ | `super_run` | `create` `plan` `show` `recover` `complete` | Run lifecycle; `recover` increases the generation and re-reconciles |
150
+ | `super_anchor` | `show` `apply` `history` | Versioned anchors; corrections explicitly invalidate affected work |
151
+ | `super_mandate` | `prepare` `bind` `bindReviewer` `report` `show` | Delegation contract and native SessionId binding |
152
+ | `super_evidence` | `record` `observe` `list` | Typed evidence with write-scope and source-role checks |
153
+ | `super_review` | `evaluate` `decide` `release` | Independent acceptance and release |
154
+ | `super_route` | `show` `set` `inspect` `switch` | Model policy for the current run with bounded failover |
155
+ | `super_snapshot` | `{}` | Read-only check of Run / gate / proof / recovery |
157
156
 
158
- 每个写动作都带 `expectedRevision` / `expectedGeneration`,冲突即拒绝,不会静默覆盖。
157
+ Every write action carries `expectedRevision` and `expectedGeneration`; conflicts are rejected instead of silently overwritten.
159
158
 
160
- ## 右栏监管面板
159
+ ## Right panel
161
160
 
162
- ![Right panel anatomy](docs/images/panel-mockup.png)
161
+ ![Right panel](docs/images/en/panel-mockup.png)
163
162
 
164
- - 面板是**只读投影**:`目标/Anchor`、`模型策略与路由审计`、`工作项`、`Mandate`、`证据与门禁`、`审计时间线`、`议程/attempt`。
165
- - 面板不写状态;所有变更只能由 `super_*` 工具穿过 Host 的 CAS 校验完成。
166
- - composer 入口不阻塞输入,普通会话看不到该入口。
163
+ - The panel is a **read-only projection**: objective/Anchor, model policy and routing audit, work items, Mandate, evidence and gates, audit timeline, agenda/attempt.
164
+ - It never writes state; only `super_*` tools can change state, through the Host CAS check.
165
+ - The composer entry never blocks input and is invisible in ordinary sessions.
167
166
 
168
- ## 证据门与安全边界
167
+ ## Evidence gates and boundaries
169
168
 
170
- | 规则 | 行为 |
169
+ | Rule | Behavior |
171
170
  | --- | --- |
172
- | 证据三态 | `pass` 才可能放行;`fail` 阻塞;`unknown` 不当作通过 |
173
- | 来源角色 | 证据必须来自允许的角色与写域,跨项复用的旧证据会被标记 stale |
174
- | Reviewer 只读 | 写操作、未知 shell、权限提升指令一律 fail-closed;只读命令按参数分类 |
175
- | 提交顺序 | `SnapshotProof` → `storageDomain` → live core;任一步失败即中止 |
176
- | 恢复 | `recover` 增加 generation,旧证据不复用;quarantine 只允许 root Lead 处理 |
177
- | 沙箱边界 | 本插件**不提供**操作系统级文件权限沙箱,写域是协作契约 |
178
- | 信任边界 | SnapshotProof 依赖原生会话日志,不防御恶意宿主或直接篡改原生日志 |
171
+ | Three evidence states | Only `pass` may release; `fail` blocks; `unknown` is never treated as success |
172
+ | Source roles | Evidence must come from an allowed role and write scope; evidence reused across items is marked stale |
173
+ | Reviewer read-only | Writes, unknown shell commands and privilege escalation fail closed; read commands are classified by arguments |
174
+ | Commit order | `SnapshotProof` -> `storageDomain` -> live core; any failed step aborts |
175
+ | Recovery | `recover` increases the generation and old evidence is not reused; only the root Lead may clear quarantine |
176
+ | Sandbox scope | This plugin does not provide an OS-level file sandbox; write scopes are a coordination contract |
177
+ | Trust boundary | SnapshotProof relies on the native session log and does not defend against a malicious host or direct log tampering |
179
178
 
180
- ## 兼容性
179
+ ## Compatibility
181
180
 
182
- | 项 | 值 |
181
+ | Item | Value |
183
182
  | --- | --- |
184
- | DSH | `>=0.2.2-rc.3 <0.3.0-0`(开发与验证基线 `0.2.2-rc.5`) |
183
+ | DSH | `>=0.2.2-rc.3 <0.3.0-0` (development baseline `0.2.2-rc.5`) |
185
184
  | Node | `^22.19.0 || >=24.0.0` |
186
- | 宿主侧 peer | `dsh-session`、`dsh-storage-domain`、`dsh-tools`、`react` |
187
- | 客户端 | web surface,`@deepseek-ai/dsh-client-connection`、`ui-conversation`、`ui-sidebar-right`、`ui-subagent` |
185
+ | Host peers | `dsh-session`, `dsh-storage-domain`, `dsh-tools`, `react` |
186
+ | Client | web surface; `@deepseek-ai/dsh-client-connection`, `ui-conversation`, `ui-sidebar-right`, `ui-subagent` |
188
187
 
189
- ## 验证
188
+ ## Verification
190
189
 
191
- - 自动化:**176 / 176 pass**,`typecheck` 与 `build` 均 exit 0。
192
- - 真实桌面链路:两条独立 Electron 会话完成监督闭环,含跨代恢复(generation 1→4)、多次 Anchor 修订、独立 Reviewer 放行与 SnapshotProof 对齐。
193
- - 修复记录:Reviewer 只读 guard 曾把 `pwsh "$env:NAME"` 误判为写操作;已按实际参数分类并加入回归用例。
194
- - 详细证据摘要见 [docs/VALIDATION.md](docs/VALIDATION.md)。
190
+ - Automation: **176 / 176 pass**; `typecheck` and `build` both exit 0.
191
+ - Real desktop runs: two independent Electron sessions completed supervision loops, including recovery across generations, repeated Anchor revisions, independent Reviewer release and SnapshotProof agreement.
192
+ - Fixes recorded: the Reviewer read-only guard once classified `pwsh "$env:NAME"` as a write; it now classifies by arguments and has regression tests.
193
+ - Details: [docs/VALIDATION.md](docs/VALIDATION.md).
195
194
 
196
- ### 明确未覆盖
195
+ ### Known unknown
197
196
 
198
- - 真实 provider 故障下的自动切换、预算耗尽 blocked、`model.select` 失败分支:尚未在实机发生,保持 unknown。
199
- - 未提供全局文件权限沙箱;不承诺跨会话隔离之外的安全边界。
197
+ - Live provider-failure failover, budget-exhaustion blocking and `model.select` failure branches have never occurred on real hardware and remain unknown.
198
+ - No OS-level file sandbox; no security boundary beyond session isolation.
200
199
 
201
- ## 常见问题
200
+ ## FAQ
202
201
 
203
- **Q:选了预设但没有 `super_*` 工具?**
204
- 只有 `super-agent` 会话与已绑定且验证过的只读 Reviewer 才拿到工具;确认预设确实切换成功,并完全重启 DSH。
202
+ **I selected the preset but there are no `super_*` tools.**
203
+ Only `super-agent` sessions and a verified, bound read-only Reviewer receive the tools. Confirm the preset actually switched and restart DSH completely.
205
204
 
206
- **Q:Reviewer 一直无法 decide?**
207
- 查看门禁返回的 `missingEvidence` / `staleEvidence` / `REVIEWER_NOT_READONLY`:前者补证据,后者说明 Reviewer 有过写回执,需换新的只读 Reviewer。
205
+ **The Reviewer cannot decide.**
206
+ Read the gate response: `missingEvidence` / `staleEvidence` means you need new evidence; `REVIEWER_NOT_READONLY` means the Reviewer produced a write receipt and must be replaced by a fresh read-only Reviewer.
208
207
 
209
- **Q:崩溃后 Run 状态怎么恢复?**
210
- root Lead 调用 `super_run recover`;generation 会增加,旧证据不复用,需要在新 generation 重新取证。
208
+ **How do I recover after a crash?**
209
+ The root Lead calls `super_run recover`; the generation increases, old evidence is not reused, and new evidence must be collected in the new generation.
211
210
 
212
- **Q:能当全局路由/自动降级用吗?**
213
- 不能。`super_route` 只管理当前 Run 的显式策略;没有 out-of-the-box 的全局自动路由。
211
+ **Can it act as a global router or automatic downgrade?**
212
+ No. `super_route` only manages an explicit policy for the current run; there is no out-of-the-box global auto-router.
214
213
 
215
- ## 开发与贡献
214
+ ## Development
216
215
 
217
216
  ```bash
218
217
  pnpm install
219
218
  pnpm typecheck && pnpm build && pnpm test
220
219
  ```
221
220
 
222
- - 目录:`src/core`(纯状态机,无 Host 依赖)、`src/host`(工具、guard、routing、存储)、`src/client`(面板与入口)、`test/`。
223
- - 提交前请保持 `typecheck`、`build`、`test` 全绿;核心状态机改动需补正反例。
224
- - 欢迎 Issue / PR:https://github.com/BioAIEvolu/dsh-superagent-ptc/issues
221
+ - Layout: `src/core` (pure state machine, no Host dependency), `src/host` (tools, guard, routing, storage), `src/client` (panel and entry), `test/`.
222
+ - Keep `typecheck`, `build` and `test` green; core state-machine changes need positive and negative cases.
223
+ - Issues and PRs: https://github.com/BioAIEvolu/dsh-superagent-ptc/issues
225
224
 
226
- ## 致谢
225
+ ## Acknowledgements
227
226
 
228
- 这个插件的方向不是凭空想出来的,来自 2026-11-17 一次真实的群聊讨论与源码分享:
227
+ This plugin did not appear from thin air. It grew out of a real group discussion and source share on 2026-11-17:
229
228
 
230
- - **群友 CC**:分享了 `dsh-plugin-antidrift` 插件源码,并给出真实的长任务经验——用 `/goal` 设置长期目标、单次跑过 30+ 小时、一次开 10 个 agent 并行写。本项目对其源码只做取证阅读(未安装、未运行、未复制代码),其“锚点 + 委派 + 审计”的思路是重要的早期启发。
231
- - **桉**:提出“一次性部署多条指令、每几条插入一次小审计、不紧急就继续”的节奏,直接对应本项目“工作项 + 证据门 + 失败预算”的取舍。
232
- - **Electron**:在讨论中把这种形态认作 PTC 模式的延伸,促使我们确认“PTC 只有 `run_code`,监管必须建立在其原生事件链之上”。
233
- - **KOLA 2**:提出“定时轮询检查进度、完成就释放下一条命令与审计”,以及“主 router 控制 worker 干活”的 SuperAgent 思路,这两点分别影响了 Mandate 的解锁语义与 Lead/Worker/Reviewer 的角色划分。
229
+ - **CC**, a community member, shared the `dsh-plugin-antidrift` plugin source and real long-run experience (setting a long-term `/goal`, a single run lasting 30+ hours, ten agents writing in parallel). We only read the source for forensics — it was never installed, executed or copied — and its "anchor + delegation + audit" framing was an early inspiration.
230
+ - **An** proposed deploying several instructions at once with a small audit every few steps, which maps directly to the work item / evidence gate / failure budget trade-off here.
231
+ - **Electron** read this shape as an extension of PTC, which pushed us to state that PTC only exposes `run_code` and that supervision must sit on its native event chain.
232
+ - **KOLA 2** proposed polling progress and releasing the next instruction plus audit on completion, and the "main router controlling workers" SuperAgent idea; these shaped Mandate unlock semantics and the Lead/Worker/Reviewer split.
234
233
 
235
- 另外感谢上游参考 `zouyuanqing/dsh-super-ptc-mode`(MIT):本项目参考了其轻量 preset 组合方式与 Lead 委派理念,persona 与组合已按当前 DSH 契约重写,许可与出处保留在 [NOTICE.md](NOTICE.md)。
234
+ Thanks also to upstream `zouyuanqing/dsh-super-ptc-mode` (MIT): we referenced its thin preset composition and Lead delegation doctrine, then rewrote the persona and composition for the current DSH contract. License and provenance are preserved in [NOTICE.md](NOTICE.md).
236
235
 
237
- 以及所有在群里继续讨论、提问和纠正的人——这些对话让“证据放行”从一句口号变成了可验证的状态机。
236
+ And thanks to everyone who kept discussing, asking and correcting in that group — those conversations turned "evidence-gated release" from a slogan into a state machine.
238
237
 
239
- ## 许可
238
+ ## License
240
239
 
241
- MIT License,见 [LICENSE](LICENSE)。上游 DSH 组件版权与来源见 [NOTICE.md](NOTICE.md)。
240
+ MIT, see [LICENSE](LICENSE). Upstream DSH component notices are recorded in [NOTICE.md](NOTICE.md).
@@ -0,0 +1,240 @@
1
+ # SuperAgent PTC
2
+
3
+ [英文](README.md) | **简体中文**
4
+
5
+ [![npm 版本](https://img.shields.io/npm/v/dsh-superagent-ptc?color=cb3837)](https://www.npmjs.com/package/dsh-superagent-ptc)
6
+ [![npm 下载量](https://img.shields.io/npm/dm/dsh-superagent-ptc?color=blue)](https://www.npmjs.com/package/dsh-superagent-ptc)
7
+ [![许可 MIT](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
8
+ [![DSH](https://img.shields.io/badge/DSH-0.2.2--rc.5-6f42c1)](https://github.com/deepseek-ai/deepseek-harness)
9
+ [![测试](https://img.shields.io/badge/tests-176%2F176-brightgreen)](docs/VALIDATION.md)
10
+
11
+ > **DeepSeek Harness 的长任务监督层**——版本化锚点、有界委派、独立验收、证据放行。
12
+
13
+ SuperAgent PTC 把“模型说自己做完了”变成“独立验收者证明它做完了”。它是 **preset-first** 插件:在原生 PTC / Agent / Goal / Teams 运行时之上叠加一层监管,不另造 Agent loop、任务板或路由器。
14
+
15
+ ```text
16
+ 你:把这份调研拆成三项工作,逐个验收后再写总结
17
+ PTC:Run + Anchor → 逐项 Mandate 派给 Worker → standard Reviewer 独立核验
18
+ → 证据通过才放行 → super_snapshot 返回可验证的 revision 与 proof
19
+ ```
20
+
21
+ ![分层架构](docs/images/zh/architecture-layers.png)
22
+
23
+ ## 目录
24
+
25
+ - [为什么需要它](#为什么需要它)
26
+ - [特性](#特性)
27
+ - [双层架构](#双层架构)
28
+ - [监督循环](#监督循环)
29
+ - [安装](#安装)
30
+ - [快速上手](#快速上手)
31
+ - [工具](#工具)
32
+ - [右栏面板](#右栏面板)
33
+ - [证据门与边界](#证据门与边界)
34
+ - [兼容性](#兼容性)
35
+ - [验证](#验证)
36
+ - [常见问题](#常见问题)
37
+ - [开发](#开发)
38
+ - [致谢](#致谢)
39
+ - [许可](#许可)
40
+
41
+ ## 为什么需要它
42
+
43
+ 长任务失败通常不是“模型不会写”,而是四件事没有被约束:
44
+
45
+ | 常见问题 | 后果 | SuperAgent PTC 的做法 |
46
+ | --- | --- | --- |
47
+ | 目标在长对话里漂移 | 做到一半换了题目 | **版本化 Anchor**:目标、完成定义与义务都有版本,纠正会显式失效旧工作 |
48
+ | 模型自报完成 | “done” 却没有验证 | `reported_done ≠ accepted`,必须先过独立 Reviewer 与证据门 |
49
+ | 委派没有边界 | Worker 越权或重复劳动 | **Mandate 委派合同**:工作项、写域、模型路由与 attempt 在 prepare 时冻结 |
50
+ | 崩溃后状态不明 | 不知道哪里可信 | **SnapshotProof + RunState v2**:先写原生证明,再落存储,最后替换 live core |
51
+
52
+ ## 特性
53
+
54
+ - **Preset-first**:与标准、创造、PTC、极简并列的一个 Agent 预设(`SuperAgent PTC`),不改默认模型、权限或其他会话。
55
+ - **七项监管工具**:`super_run`、`super_anchor`、`super_mandate`、`super_evidence`、`super_review`、`super_route`、`super_snapshot`,全部通过 PTC 的 `run_code` 调用,不新增脚本工具。
56
+ - **原生身份绑定**:Worker 与 Reviewer 都是真实原生子 Agent;Host 用原生 `sendMessage` 唤醒绑定的 Reviewer,Lead 无法自己扮演验收者。
57
+ - **独立只读验收**:Reviewer 必须使用原生 `standard` 预设;守卫对写操作与未知 shell 一律 fail-closed,`pwsh` 的只读命令(含读取 `$env:`)按实际参数分类。
58
+ - **分型证据门**:证据只有 `pass / fail / unknown` 三态;`unknown` 不放行;构建日志、单测与截图不能替代运行时证据。
59
+ - **失败预算与可恢复审计**:同一指纹达到预算即阻塞;`super_run recover` 增加 generation 并保留完整审计链。
60
+ - **客户端可视化**:右栏监管面板与 composer 入口,只读投影。
61
+ - **零全局副作用**:普通会话没有 `super_*` 工具、没有提示词段落、没有面板。
62
+
63
+ ### 明确不做什么
64
+
65
+ | 不做 | 原因 |
66
+ | --- | --- |
67
+ | 不重建 Agent loop、任务板或全局路由 | 原生 Session、Agent、Goal、Teams 才是执行权威 |
68
+ | 不提供操作系统级文件权限沙箱 | 写域是协作契约,不是内核隔离 |
69
+ | 不做自动模型降级 | 只支持显式、白名单、预算内的有界故障切换 |
70
+ | 不把 `reported_done` 当作验收 | 只有独立 Reviewer 加证据门才产生 `accepted` |
71
+
72
+ ## 双层架构
73
+
74
+ **一句话定位**:SuperAgent PTC 在宿主原生 Agent/Session 机制之上叠加一层监管状态机(`Run → Anchor → Mandate → Evidence → Decision`),把原生 agent 会话按角色(Lead / Worker / Reviewer)绑定进这条监管链;**PTC 的原生事件链**(`run_code` 调用与工具回执)**是整条链的证据底座**——监管层自己不产生第二套事件流。
75
+
76
+ 监管面(Control Plane)只回答“能不能放行”,执行面(Execution Plane)只回答“实际做了什么”,两者之间只有一条契约膜:`super_*` 工具是状态与证据的唯一写入口。
77
+
78
+ ![双层架构](docs/images/zh/architecture-dual.png)
79
+
80
+ - **A 监督面**:Lead 维护 Anchor 与义务账本;Mandate 冻结工作项、写域、路由与 attempt;证据门与预算决定放行。
81
+ - **契约膜**:任何状态变更都必须穿过 `super_*` 的 CAS 校验,双层之间没有第二套写路径。
82
+ - **B 执行面**:PTC `run_code` 编排宿主工具、原生 `subagent` 创建 Worker 与 Reviewer,回执以 `reported_done` 与工具结果的形式返回。
83
+ - **共同底座**:原生运行时提供身份、生命周期与证明;`storageDomain RunState v2` 与 `SnapshotProof` 让 Run 可恢复。
84
+
85
+ ## 监督循环
86
+
87
+ ![监督循环](docs/images/zh/lifecycle.png)
88
+
89
+ ```text
90
+ super_run create # 目标 + 完成定义 + 门禁策略
91
+ super_run plan # 工作项 / 依赖 / 义务(开放账本)
92
+ super_anchor # 版本化锚点;纠正会失效受影响的工作
93
+ super_mandate prepare # 冻结工作项、写域、模型路由、attempt
94
+ super_mandate bind # 绑定原生 Worker 的 SessionId
95
+ super_mandate bindReviewer # 绑定 standard Reviewer 并由 Host 原生唤醒
96
+ super_evidence record # 分型、可追溯的证据
97
+ super_review evaluate # 门禁评估
98
+ super_review decide/release # 门禁通过才放行
99
+ super_snapshot # 只读核对 revision / generation / proof
100
+ ```
101
+
102
+ ## 安装
103
+
104
+ 要求 DSH `>=0.2.2-rc.3 <0.3.0-0`,Node `^22.19.0 || >=24`。
105
+
106
+ ```bash
107
+ # 从 npm 安装到当前 profile
108
+ dsh plugin --profile desktop add dsh-superagent-ptc
109
+ ```
110
+
111
+ 安装后**完全退出并重新启动 DSH**,然后新建会话,在预设选择器中选择 **SuperAgent PTC**。
112
+
113
+ ### 通过 DSH 插件市场索引安装
114
+
115
+ 在 DSH → 设置 → 插件 → 发现 中添加下面的索引 URL,然后搜索 `SuperAgent PTC`:
116
+
117
+ ```text
118
+ https://raw.githubusercontent.com/BioAIEvolu/dsh-superagent-ptc/main/market-index.json
119
+ ```
120
+
121
+ 该索引已通过官方 `parseMarketIndex` 校验,解析为 `dsh-superagent-ptc@0.1.3`。
122
+
123
+ ### 本地开发安装
124
+
125
+ ```bash
126
+ git clone https://github.com/BioAIEvolu/dsh-superagent-ptc.git
127
+ dsh plugin --profile desktop add link:/absolute/path/to/dsh-superagent-ptc
128
+ ```
129
+
130
+ ## 快速上手
131
+
132
+ 1. 新建会话,选择 **SuperAgent PTC** 预设。
133
+ 2. 把目标与完成标准说清楚,例如:
134
+
135
+ ```text
136
+ 用 SuperAgent PTC 做最小监管闭环:
137
+ super_run create 建 Run;plan 两个工作项,W1 读 README 并给 3 条要点,W2 依赖 W1 本阶段保持 held;
138
+ Worker 继承 super-agent,Reviewer 使用 agent_preset=standard;
139
+ prepare/bind/bindReviewer 后由 Reviewer 独立记录 coverage 证据并 evaluate/decide/release;
140
+ 最后 super_snapshot 报告真实 Run/WorkItem/Mandate/Evidence/Decision ID 与 revision/generation/proof。
141
+ ```
142
+
143
+ 3. 点击 composer 上方的 **Super Agent 监管**,右栏会显示实时 Run 与审计时间线。
144
+
145
+ ## 工具
146
+
147
+ | 工具 | 动作 | 说明 |
148
+ | --- | --- | --- |
149
+ | `super_run` | `create` `plan` `show` `recover` `complete` | Run 生命周期;`recover` 增加 generation 并重新对账 |
150
+ | `super_anchor` | `show` `apply` `history` | 版本化锚点;纠正会显式失效受影响的工作 |
151
+ | `super_mandate` | `prepare` `bind` `bindReviewer` `report` `show` | 委派合同与原生 SessionId 绑定 |
152
+ | `super_evidence` | `record` `observe` `list` | 分型证据,带写域与来源角色校验 |
153
+ | `super_review` | `evaluate` `decide` `release` | 独立验收与放行 |
154
+ | `super_route` | `show` `set` `inspect` `switch` | 当前 Run 的模型策略与有界故障切换 |
155
+ | `super_snapshot` | `{}` | 只读核对 Run / 门禁 / proof / recovery |
156
+
157
+ 每个写动作都带 `expectedRevision` 与 `expectedGeneration`;冲突会被拒绝,而不是静默覆盖。
158
+
159
+ ## 右栏面板
160
+
161
+ ![右栏面板](docs/images/zh/panel-mockup.png)
162
+
163
+ - 面板是**只读投影**:目标/Anchor、模型策略与路由审计、工作项、Mandate、证据与门禁、审计时间线、议程与 attempt。
164
+ - 面板不写状态;只有 `super_*` 工具能穿过 Host 的 CAS 校验修改状态。
165
+ - composer 入口不阻塞输入,普通会话看不到它。
166
+
167
+ ## 证据门与边界
168
+
169
+ | 规则 | 行为 |
170
+ | --- | --- |
171
+ | 证据三态 | 只有 `pass` 可能放行;`fail` 阻塞;`unknown` 绝不当作成功 |
172
+ | 来源角色 | 证据必须来自允许的角色与写域;跨项复用的证据会被标为 stale |
173
+ | Reviewer 只读 | 写操作、未知 shell、提权指令一律 fail-closed;只读命令按参数分类 |
174
+ | 提交顺序 | `SnapshotProof` → `storageDomain` → live core;任一步失败即中止 |
175
+ | 恢复 | `recover` 增加 generation,旧证据不复用;只有 root Lead 能处理 quarantine |
176
+ | 沙箱范围 | 本插件不提供操作系统级文件沙箱;写域是协作契约 |
177
+ | 信任边界 | SnapshotProof 依赖原生会话日志,不防御恶意宿主或直接篡改日志 |
178
+
179
+ ## 兼容性
180
+
181
+ | 项 | 值 |
182
+ | --- | --- |
183
+ | DSH | `>=0.2.2-rc.3 <0.3.0-0`(开发基线 `0.2.2-rc.5`) |
184
+ | Node | `^22.19.0 || >=24.0.0` |
185
+ | 宿主 peer | `dsh-session`、`dsh-storage-domain`、`dsh-tools`、`react` |
186
+ | 客户端 | web surface;`@deepseek-ai/dsh-client-connection`、`ui-conversation`、`ui-sidebar-right`、`ui-subagent` |
187
+
188
+ ## 验证
189
+
190
+ - 自动化:**176 / 176 通过**;`typecheck` 与 `build` 均退出码 0。
191
+ - 真实桌面运行:两个独立 Electron 会话完成监督闭环,包含跨代恢复、多次 Anchor 修订、独立 Reviewer 放行与 SnapshotProof 对齐。
192
+ - 修复记录:Reviewer 只读守卫曾把 `pwsh "$env:NAME"` 判为写操作,现按参数分类并带回归测试。
193
+ - 细节见 [docs/VALIDATION.md](docs/VALIDATION.md)。
194
+
195
+ ### 已知未知
196
+
197
+ - 真实 provider 故障切换、预算耗尽阻塞、`model.select` 失败分支从未在实机发生,保持 unknown。
198
+ - 不提供操作系统级文件沙箱,除会话隔离外没有额外安全边界。
199
+
200
+ ## 常见问题
201
+
202
+ **选了预设但没有 `super_*` 工具?**
203
+ 只有 `super-agent` 会话与已验证的只读 Reviewer 才有工具。确认预设确实切换,并完全重启 DSH。
204
+
205
+ **Reviewer 一直无法 decide?**
206
+ 看门禁返回:`missingEvidence` / `staleEvidence` 需要补新证据;`REVIEWER_NOT_READONLY` 说明 Reviewer 产生过写回执,需要换一个全新的只读 Reviewer。
207
+
208
+ **崩溃后怎么恢复?**
209
+ root Lead 调用 `super_run recover`;generation 会增加,旧证据不复用,必须在新 generation 重新取证。
210
+
211
+ **能当全局路由或自动降级用吗?**
212
+ 不能。`super_route` 只管理当前 Run 的显式策略,没有开箱即用的全局自动路由。
213
+
214
+ ## 开发
215
+
216
+ ```bash
217
+ pnpm install
218
+ pnpm typecheck && pnpm build && pnpm test
219
+ ```
220
+
221
+ - 目录:`src/core`(纯状态机,无 Host 依赖)、`src/host`(工具、守卫、路由、存储)、`src/client`(面板与入口)、`test/`。
222
+ - 保持 `typecheck`、`build`、`test` 全绿;核心状态机改动需要正反例。
223
+ - Issue 与 PR:https://github.com/BioAIEvolu/dsh-superagent-ptc/issues
224
+
225
+ ## 致谢
226
+
227
+ 这个插件不是凭空想出来的,来自 2026-11-17 一次真实的群聊讨论与源码分享:
228
+
229
+ - **群友 CC**:分享了 `dsh-plugin-antidrift` 插件源码与真实长任务经验(用 `/goal` 设置长期目标、单次跑过 30+ 小时、一次开 10 个 agent 并行写)。本项目只做源码取证阅读(未安装、未运行、未复制代码),其“锚点 + 委派 + 审计”思路是重要早期启发。
230
+ - **桉**:提出“一次性部署多条指令、每几条插入一次小审计、不紧急就继续”,直接对应本项目的工作项 / 证据门 / 失败预算取舍。
231
+ - **Electron**:把这种形态认作 PTC 的延伸,促使我们确认“PTC 只有 `run_code`,监管必须建立在原生事件链上”。
232
+ - **KOLA 2**:提出定时轮询检查进度、完成即释放下一条命令与审计,以及“主 router 控制 worker”的 SuperAgent 思路,分别影响了 Mandate 的解锁语义与 Lead/Worker/Reviewer 角色划分。
233
+
234
+ 同时感谢上游参考 `zouyuanqing/dsh-super-ptc-mode`(MIT):参考了其轻量 preset 组合与 Lead 委派理念,persona 与组合已按当前 DSH 契约重写,许可与出处保留在 [NOTICE.md](NOTICE.md)。
235
+
236
+ 也感谢群里持续讨论、提问与纠正的每个人——这些对话让“证据放行”从一句口号变成了可验证的状态机。
237
+
238
+ ## 许可
239
+
240
+ MIT,见 [LICENSE](LICENSE)。上游 DSH 组件声明记录在 [NOTICE.md](NOTICE.md)。
@@ -0,0 +1,52 @@
1
+ <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 680 592" width="100%" font-family="system-ui,sans-serif">
2
+ <title>SuperAgent PTC 双层架构</title>
3
+ <defs>
4
+ <marker id="a1" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse"><path d="M0,0 L10,5 L0,10 Z" fill="#85B7EB"/></marker>
5
+ <marker id="a2" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse"><path d="M0,0 L10,5 L0,10 Z" fill="#AFA9EC"/></marker>
6
+ <marker id="a3" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse"><path d="M0,0 L10,5 L0,10 Z" fill="#5DCAA5"/></marker>
7
+ </defs>
8
+ <text x="40" y="26" font-size="15" font-weight="600" fill="#1F2937">SuperAgent PTC 双层架构</text>
9
+ <text x="40" y="44" font-size="12" fill="#1F2937" opacity="0.65">监督面决定「能不能放行」,执行面决定「实际做了什么」</text>
10
+ <rect x="40" y="58" width="12" height="12" rx="3" fill="#B5D4F4"/><text x="58" y="68" font-size="12" fill="#1F2937">监督面</text>
11
+ <rect x="140" y="58" width="12" height="12" rx="3" fill="#CECBF6"/><text x="158" y="68" font-size="12" fill="#1F2937">执行面</text>
12
+ <rect x="240" y="58" width="12" height="12" rx="3" fill="#9FE1CB"/><text x="258" y="68" font-size="12" fill="#1F2937">原生运行时</text>
13
+ <rect x="40" y="96" width="600" height="168" rx="12" fill="#F6F8FA" stroke="#D0D7DE"/>
14
+ <text x="52" y="116" font-size="12" font-weight="600" fill="#1F2937" opacity="0.75">A 监督面(Control Plane)</text>
15
+ <rect x="56" y="126" width="276" height="52" rx="8" fill="#B5D4F4" stroke="#85B7EB"/>
16
+ <text x="70" y="148" font-size="13" font-weight="600" fill="#0C447C">Lead · 目标与 Anchor</text>
17
+ <text x="70" y="167" font-size="11" fill="#0C447C" opacity="0.8">版本化锚点 · 义务 · 纠正</text>
18
+ <rect x="348" y="126" width="276" height="52" rx="8" fill="#B5D4F4" stroke="#85B7EB"/>
19
+ <text x="362" y="148" font-size="13" font-weight="600" fill="#0C447C">Mandate 委派合同</text>
20
+ <text x="362" y="167" font-size="11" fill="#0C447C" opacity="0.8">工作项 · 写域 · 路由 · attempt</text>
21
+ <rect x="56" y="196" width="276" height="52" rx="8" fill="#B5D4F4" stroke="#85B7EB"/>
22
+ <text x="70" y="218" font-size="13" font-weight="600" fill="#0C447C">Worker 与 Reviewer</text>
23
+ <text x="70" y="237" font-size="11" fill="#0C447C" opacity="0.8">原生 SessionId 绑定;Reviewer 只读</text>
24
+ <rect x="348" y="196" width="276" height="52" rx="8" fill="#B5D4F4" stroke="#85B7EB"/>
25
+ <text x="362" y="218" font-size="13" font-weight="600" fill="#0C447C">证据门与放行</text>
26
+ <text x="362" y="237" font-size="11" fill="#0C447C" opacity="0.8">pass / fail / unknown;独立验收</text>
27
+ <rect x="40" y="288" width="600" height="48" rx="8" fill="#F6F8FA" stroke="#85B7EB" stroke-dasharray="6 4"/>
28
+ <text x="56" y="317" font-size="11" fill="#1F2937" opacity="0.8">契约膜:super_* 是状态与证据的唯一写入口(CAS)</text>
29
+ <rect x="40" y="360" width="600" height="152" rx="12" fill="#F6F8FA" stroke="#D0D7DE"/>
30
+ <text x="52" y="380" font-size="12" font-weight="600" fill="#1F2937" opacity="0.75">B 执行面(Execution Plane)</text>
31
+ <rect x="56" y="390" width="276" height="50" rx="8" fill="#CECBF6" stroke="#AFA9EC"/>
32
+ <text x="70" y="412" font-size="13" font-weight="600" fill="#3C3489">run_code 编排</text>
33
+ <text x="70" y="431" font-size="11" fill="#3C3489" opacity="0.8">TypeScript 调用宿主工具</text>
34
+ <rect x="348" y="390" width="276" height="50" rx="8" fill="#CECBF6" stroke="#AFA9EC"/>
35
+ <text x="362" y="412" font-size="13" font-weight="600" fill="#3C3489">宿主工具面</text>
36
+ <text x="362" y="431" font-size="11" fill="#3C3489" opacity="0.8">read / write / pwsh / grep / glob 等</text>
37
+ <rect x="56" y="452" width="276" height="50" rx="8" fill="#CECBF6" stroke="#AFA9EC"/>
38
+ <text x="70" y="474" font-size="13" font-weight="600" fill="#3C3489">原生 subagent 派发</text>
39
+ <text x="70" y="493" font-size="11" fill="#3C3489" opacity="0.8">Lead 创建 Worker 与 Reviewer</text>
40
+ <rect x="348" y="452" width="276" height="50" rx="8" fill="#CECBF6" stroke="#AFA9EC"/>
41
+ <text x="362" y="474" font-size="13" font-weight="600" fill="#3C3489">执行回执</text>
42
+ <text x="362" y="493" font-size="11" fill="#3C3489" opacity="0.8">reported_done · 工具结果 · 证据素材</text>
43
+ <rect x="40" y="522" width="600" height="56" rx="8" fill="#9FE1CB" stroke="#5DCAA5"/>
44
+ <text x="54" y="546" font-size="13" font-weight="600" fill="#085041">原生运行时:Session / Agent / Teams + storageDomain 与 SnapshotProof</text>
45
+ <text x="54" y="565" font-size="11" fill="#085041" opacity="0.8">两层共享的底座</text>
46
+ <line x1="460" y1="264" x2="460" y2="356" stroke="#85B7EB" stroke-width="2" marker-end="url(#a1)"/>
47
+ <line x1="560" y1="356" x2="560" y2="268" stroke="#5DCAA5" stroke-width="2" marker-end="url(#a3)"/>
48
+ <line x1="196" y1="502" x2="196" y2="526" stroke="#AFA9EC" stroke-width="2" stroke-dasharray="6 4" marker-end="url(#a2)"/>
49
+ <text x="494" y="352" font-size="10" text-anchor="end" fill="#1F2937" opacity="0.75">委派:mandate</text>
50
+ <text x="566" y="352" font-size="10" fill="#1F2937" opacity="0.75">回传:证据</text>
51
+ <text x="204" y="520" font-size="11" fill="#1F2937" opacity="0.75">原生工具与 subagent</text>
52
+ </svg>
@@ -0,0 +1,60 @@
1
+ <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 680 560" width="100%" font-family="system-ui,sans-serif">
2
+ <title>SuperAgent PTC layered architecture</title>
3
+ <defs>
4
+ <marker id="a1" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse"><path d="M0,0 L10,5 L0,10 Z" fill="#85B7EB"/></marker>
5
+ <marker id="a2" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse"><path d="M0,0 L10,5 L0,10 Z" fill="#AFA9EC"/></marker>
6
+ <marker id="a3" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse"><path d="M0,0 L10,5 L0,10 Z" fill="#5DCAA5"/></marker>
7
+ </defs>
8
+ <text x="40" y="26" font-size="15" font-weight="600" fill="#1F2937">SuperAgent PTC 架构(当前实现)</text>
9
+ <text x="40" y="44" font-size="12" fill="#1F2937" opacity="0.65">建立于原生 DSH 运行时之上的 preset-first 监管层</text>
10
+ <rect x="40" y="58" width="12" height="12" rx="3" fill="#B5D4F4"/><text x="58" y="68" font-size="12" fill="#1F2937">监管层</text>
11
+ <rect x="190" y="58" width="12" height="12" rx="3" fill="#FAC775"/><text x="208" y="68" font-size="12" fill="#1F2937">Reviewer</text>
12
+ <rect x="340" y="58" width="12" height="12" rx="3" fill="#CECBF6"/><text x="358" y="68" font-size="12" fill="#1F2937">原生运行时</text>
13
+ <rect x="490" y="58" width="12" height="12" rx="3" fill="#9FE1CB"/><text x="508" y="68" font-size="12" fill="#1F2937">持久化与证明</text>
14
+ <rect x="40" y="104" width="600" height="88" rx="10" fill="#F6F8FA" stroke="#D0D7DE"/>
15
+ <text x="52" y="122" font-size="12" fill="#1F2937" opacity="0.7">① 角色</text>
16
+ <rect x="56" y="130" width="186" height="50" rx="8" fill="#B5D4F4" stroke="#85B7EB"/>
17
+ <text x="70" y="152" font-size="13" font-weight="600" fill="#0C447C">Lead</text>
18
+ <text x="70" y="171" font-size="11" fill="#0C447C" opacity="0.8">super-agent 预设</text>
19
+ <rect x="256" y="130" width="160" height="50" rx="8" fill="#B5D4F4" stroke="#85B7EB"/>
20
+ <text x="270" y="152" font-size="13" font-weight="600" fill="#0C447C">Worker</text>
21
+ <text x="270" y="171" font-size="11" fill="#0C447C" opacity="0.8">继承 super-agent</text>
22
+ <rect x="430" y="130" width="194" height="50" rx="8" fill="#FAC775" stroke="#EF9F27"/>
23
+ <text x="444" y="152" font-size="13" font-weight="600" fill="#633806">Reviewer</text>
24
+ <text x="444" y="171" font-size="11" fill="#633806" opacity="0.8">standard 预设 · 只读</text>
25
+ <rect x="40" y="208" width="600" height="200" rx="10" fill="#F6F8FA" stroke="#D0D7DE"/>
26
+ <text x="52" y="226" font-size="12" fill="#1F2937" opacity="0.7">② 监管插件:全局 Host 行 + Client 模块</text>
27
+ <rect x="56" y="236" width="280" height="54" rx="8" fill="#B5D4F4" stroke="#85B7EB"/>
28
+ <text x="70" y="258" font-size="13" font-weight="600" fill="#0C447C">七项 super_* 工具</text>
29
+ <text x="70" y="277" font-size="11" fill="#0C447C" opacity="0.8">通过 PTC run_code 调用</text>
30
+ <rect x="352" y="236" width="272" height="54" rx="8" fill="#B5D4F4" stroke="#85B7EB"/>
31
+ <text x="366" y="258" font-size="13" font-weight="600" fill="#0C447C">Reviewer 只读守卫</text>
32
+ <text x="366" y="277" font-size="11" fill="#0C447C" opacity="0.8">只读分类 · fail-closed</text>
33
+ <rect x="56" y="300" width="280" height="54" rx="8" fill="#B5D4F4" stroke="#85B7EB"/>
34
+ <text x="70" y="322" font-size="13" font-weight="600" fill="#0C447C">Core 状态机</text>
35
+ <text x="70" y="341" font-size="10" fill="#0C447C" opacity="0.8">Run → Anchor → Mandate → Evidence → Decision</text>
36
+ <rect x="352" y="300" width="272" height="54" rx="8" fill="#B5D4F4" stroke="#85B7EB"/>
37
+ <text x="366" y="322" font-size="13" font-weight="600" fill="#0C447C">Client</text>
38
+ <text x="366" y="341" font-size="11" fill="#0C447C" opacity="0.8">右栏面板 + composer 入口</text>
39
+ <rect x="56" y="364" width="568" height="40" rx="8" fill="#9FE1CB" stroke="#5DCAA5"/>
40
+ <text x="70" y="386" font-size="13" font-weight="600" fill="#085041">storageDomain RunState v2 + SnapshotProof</text>
41
+ <text x="70" y="400" font-size="11" fill="#085041" opacity="0.8">先证明,再落存储,最后替换 core</text>
42
+ <rect x="40" y="426" width="600" height="88" rx="10" fill="#F6F8FA" stroke="#D0D7DE"/>
43
+ <text x="52" y="444" font-size="12" fill="#1F2937" opacity="0.7">③ 原生 DSH 运行时(执行权威)</text>
44
+ <rect x="56" y="452" width="280" height="50" rx="8" fill="#CECBF6" stroke="#AFA9EC"/>
45
+ <text x="70" y="474" font-size="13" font-weight="600" fill="#3C3489">Session, Agent, Goal, Teams</text>
46
+ <text x="70" y="493" font-size="11" fill="#3C3489" opacity="0.8">身份与生命周期权威</text>
47
+ <rect x="352" y="452" width="272" height="50" rx="8" fill="#CECBF6" stroke="#AFA9EC"/>
48
+ <text x="366" y="474" font-size="13" font-weight="600" fill="#3C3489">PTC run_code · 原生 subagent</text>
49
+ <text x="366" y="493" font-size="11" fill="#3C3489" opacity="0.8">sendMessage 唤醒 · 会话日志</text>
50
+ <line x1="149" y1="184" x2="149" y2="210" stroke="#85B7EB" stroke-width="2" marker-end="url(#a1)"/>
51
+ <line x1="527" y1="184" x2="527" y2="210" stroke="#AFA9EC" stroke-width="2" stroke-dasharray="6 4" marker-end="url(#a2)"/>
52
+ <line x1="196" y1="290" x2="196" y2="298" stroke="#85B7EB" stroke-width="2" marker-end="url(#a1)"/>
53
+
54
+ <line x1="340" y1="327" x2="350" y2="327" stroke="#AFA9EC" stroke-width="2" stroke-dasharray="6 4" marker-end="url(#a2)"/>
55
+ <line x1="196" y1="404" x2="196" y2="424" stroke="#AFA9EC" stroke-width="2" stroke-dasharray="6 4" marker-end="url(#a2)"/>
56
+ <text x="156" y="202" font-size="11" fill="#1F2937" opacity="0.75">super_*</text>
57
+ <text x="534" y="202" font-size="11" fill="#1F2937" opacity="0.75">只读</text>
58
+ <text x="204" y="418" font-size="10" fill="#1F2937" opacity="0.75">证明写入原生会话</text>
59
+ <text x="40" y="544" font-size="12" fill="#1F2937" opacity="0.6">普通会话无工具也无面板;Reviewer 只读由守卫强制</text>
60
+ </svg>
Binary file
@@ -0,0 +1,34 @@
1
+ <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 680 400" width="100%" font-family="system-ui,sans-serif">
2
+ <title>监督循环:从目标到被接受的证据</title>
3
+ <defs>
4
+ <marker id="lc1" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse"><path d="M0,0 L10,5 L0,10 Z" fill="#85B7EB"/></marker>
5
+ </defs>
6
+ <text x="40" y="26" font-size="15" font-weight="600" fill="#1F2937">监督循环:从目标到被接受的证据</text>
7
+ <text x="40" y="44" font-size="12" fill="#1F2937" opacity="0.65">每一步都是真实的工具调用,受 CAS 保护,不能跳过</text>
8
+ <rect x="40" y="58" width="12" height="12" rx="3" fill="#B5D4F4"/><text x="58" y="68" font-size="12" fill="#1F2937">监管步骤</text>
9
+ <rect x="176" y="58" width="12" height="12" rx="3" fill="#FAC775"/><text x="194" y="68" font-size="12" fill="#1F2937">独立验收门</text>
10
+ <rect x="56" y="120" width="160" height="64" rx="8" fill="#B5D4F4" stroke="#85B7EB"/>
11
+ <text x="70" y="150" font-size="13" font-weight="600" fill="#0C447C">① 建 Run</text>
12
+ <text x="70" y="170" font-size="11" fill="#0C447C" opacity="0.8">目标 + 完成定义</text>
13
+ <rect x="236" y="120" width="160" height="64" rx="8" fill="#B5D4F4" stroke="#85B7EB"/>
14
+ <text x="250" y="150" font-size="13" font-weight="600" fill="#0C447C">② 规划</text>
15
+ <text x="250" y="170" font-size="11" fill="#0C447C" opacity="0.8">工作项 + 义务</text>
16
+ <rect x="416" y="120" width="160" height="64" rx="8" fill="#B5D4F4" stroke="#85B7EB"/>
17
+ <text x="430" y="150" font-size="13" font-weight="600" fill="#0C447C">③ 委派合同</text>
18
+ <text x="430" y="170" font-size="11" fill="#0C447C" opacity="0.8">prepare + bind</text>
19
+ <rect x="56" y="232" width="160" height="64" rx="8" fill="#B5D4F4" stroke="#85B7EB"/>
20
+ <text x="70" y="262" font-size="13" font-weight="600" fill="#0C447C">④ Worker</text>
21
+ <text x="70" y="282" font-size="11" fill="#0C447C" opacity="0.8">报告不等于验收</text>
22
+ <rect x="236" y="232" width="160" height="64" rx="8" fill="#FAC775" stroke="#EF9F27"/>
23
+ <text x="250" y="262" font-size="13" font-weight="600" fill="#633806">⑤ Reviewer</text>
24
+ <text x="250" y="282" font-size="11" fill="#633806" opacity="0.85">证据 + 决定</text>
25
+ <rect x="416" y="232" width="160" height="64" rx="8" fill="#B5D4F4" stroke="#85B7EB"/>
26
+ <text x="430" y="262" font-size="13" font-weight="600" fill="#0C447C">⑥ 快照</text>
27
+ <text x="430" y="282" font-size="11" fill="#0C447C" opacity="0.8">证明 + 恢复</text>
28
+ <line x1="216" y1="152" x2="232" y2="152" stroke="#85B7EB" stroke-width="2" marker-end="url(#lc1)"/>
29
+ <line x1="396" y1="152" x2="412" y2="152" stroke="#85B7EB" stroke-width="2" marker-end="url(#lc1)"/>
30
+ <line x1="496" y1="184" x2="496" y2="228" stroke="#85B7EB" stroke-width="2" marker-end="url(#lc1)"/>
31
+ <line x1="216" y1="264" x2="232" y2="264" stroke="#85B7EB" stroke-width="2" marker-end="url(#lc1)"/>
32
+ <line x1="396" y1="264" x2="412" y2="264" stroke="#85B7EB" stroke-width="2" marker-end="url(#lc1)"/>
33
+ <text x="40" y="356" font-size="12" fill="#1F2937" opacity="0.6">Reviewer 自己记录 coverage 证据,再 decide/release;Lead 不代审</text>
34
+ </svg>
Binary file
@@ -0,0 +1,33 @@
1
+ <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 680 444" width="100%" font-family="system-ui,sans-serif">
2
+ <title>右栏面板结构</title>
3
+ <defs>
4
+ <marker id="a1" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse"><path d="M0,0 L10,5 L0,10 Z" fill="#85B7EB"/></marker>
5
+ <marker id="a2" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse"><path d="M0,0 L10,5 L0,10 Z" fill="#AFA9EC"/></marker>
6
+ <marker id="a3" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse"><path d="M0,0 L10,5 L0,10 Z" fill="#5DCAA5"/></marker>
7
+ </defs>
8
+ <text x="40" y="26" font-size="15" font-weight="600" fill="#1F2937">右栏面板结构</text>
9
+ <text x="40" y="44" font-size="12" fill="#1F2937" opacity="0.65">Run 的只读投影:目标、门禁、证据与审计</text>
10
+ <rect x="40" y="70" width="600" height="330" rx="10" fill="#FFFFFF" stroke="#D0D7DE"/>
11
+ <rect x="56" y="84" width="280" height="56" rx="8" fill="#B5D4F4" stroke="#85B7EB"/>
12
+ <text x="70" y="106" font-size="13" font-weight="600" fill="#0C447C">目标与 Anchor</text>
13
+ <text x="70" y="125" font-size="11" fill="#0C447C" opacity="0.8">版本 · 工作项 · 门禁策略</text>
14
+ <rect x="348" y="84" width="276" height="56" rx="8" fill="#B5D4F4" stroke="#85B7EB"/>
15
+ <text x="362" y="106" font-size="13" font-weight="600" fill="#0C447C">模型策略与路由</text>
16
+ <text x="362" y="125" font-size="11" fill="#0C447C" opacity="0.8">允许路由 · 预算 · 故障</text>
17
+ <rect x="56" y="152" width="280" height="76" rx="8" fill="#B5D4F4" stroke="#85B7EB"/>
18
+ <text x="70" y="174" font-size="13" font-weight="600" fill="#0C447C">工作项</text>
19
+ <text x="70" y="193" font-size="11" fill="#0C447C" opacity="0.8">状态 · attempt · 当前 Mandate</text>
20
+ <rect x="348" y="152" width="276" height="76" rx="8" fill="#B5D4F4" stroke="#85B7EB"/>
21
+ <text x="362" y="174" font-size="13" font-weight="600" fill="#0C447C">Mandate</text>
22
+ <text x="362" y="193" font-size="11" fill="#0C447C" opacity="0.8">Worker / Reviewer · 写域</text>
23
+ <rect x="56" y="240" width="280" height="76" rx="8" fill="#9FE1CB" stroke="#5DCAA5"/>
24
+ <text x="70" y="262" font-size="13" font-weight="600" fill="#085041">证据与门禁</text>
25
+ <text x="70" y="281" font-size="11" fill="#085041" opacity="0.8">类型 · 结果 · 来源角色</text>
26
+ <rect x="348" y="240" width="276" height="76" rx="8" fill="#9FE1CB" stroke="#5DCAA5"/>
27
+ <text x="362" y="262" font-size="13" font-weight="600" fill="#085041">审计时间线</text>
28
+ <text x="362" y="281" font-size="11" fill="#085041" opacity="0.8">每次变更都带 revision</text>
29
+ <rect x="56" y="328" width="568" height="56" rx="8" fill="#B5D4F4" stroke="#85B7EB"/>
30
+ <text x="70" y="350" font-size="13" font-weight="600" fill="#0C447C">composer 入口:Super Agent 监管</text>
31
+ <text x="70" y="369" font-size="11" fill="#0C447C" opacity="0.8">打开面板但不阻塞输入</text>
32
+ <text x="40" y="424" font-size="12" fill="#1F2937" opacity="0.6">面板不写状态;只通过只读 RPC 读取投影</text>
33
+ </svg>
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "dsh-superagent-ptc",
3
- "version": "0.1.3",
3
+ "version": "0.1.5",
4
4
  "description": "SuperAgent PTC: long-task supervision for DeepSeek Harness. Versioned goal anchors, bounded delegation (Mandate), independent read-only Reviewer acceptance, typed evidence gates and crash-safe proof/recovery. Native PTC execution, preset-first, no second agent loop. 中文:为 DSH 长任务提供目标锚点、有界委派、独立验收与证据放行的监督层。",
5
5
  "type": "module",
6
6
  "license": "MIT",
@@ -19,6 +19,7 @@
19
19
  "LICENSE",
20
20
  "NOTICE.md",
21
21
  "README.md",
22
+ "README.zh-CN.md",
22
23
  "docs"
23
24
  ],
24
25
  "engines": {
Binary file
File without changes
File without changes