dsh-superagent-ptc 0.1.5 → 0.1.7
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.en.md +240 -0
- package/README.md +147 -147
- package/package.json +2 -2
- package/README.zh-CN.md +0 -240
package/README.en.md
ADDED
|
@@ -0,0 +1,240 @@
|
|
|
1
|
+
# SuperAgent PTC
|
|
2
|
+
|
|
3
|
+
[](README.en.md) [](README.md)
|
|
4
|
+
|
|
5
|
+
[](https://www.npmjs.com/package/dsh-superagent-ptc)
|
|
6
|
+
[](https://www.npmjs.com/package/dsh-superagent-ptc)
|
|
7
|
+
[](LICENSE)
|
|
8
|
+
[](https://github.com/deepseek-ai/deepseek-harness)
|
|
9
|
+
[](docs/VALIDATION.md)
|
|
10
|
+
|
|
11
|
+
> **Long-task supervision layer for DeepSeek Harness** — versioned anchors, bounded delegation, independent acceptance, evidence-gated release.
|
|
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.
|
|
14
|
+
|
|
15
|
+
```
|
|
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
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+

|
|
22
|
+
|
|
23
|
+
## Contents
|
|
24
|
+
|
|
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)
|
|
40
|
+
|
|
41
|
+
## Why SuperAgent PTC
|
|
42
|
+
|
|
43
|
+
Long tasks rarely fail because the model cannot write code. They fail because four things stay unconstrained:
|
|
44
|
+
|
|
45
|
+
| Problem | Consequence | What SuperAgent PTC does |
|
|
46
|
+
| --- | --- | --- |
|
|
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 |
|
|
51
|
+
|
|
52
|
+
## Features
|
|
53
|
+
|
|
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.
|
|
62
|
+
|
|
63
|
+
### What it deliberately does not do
|
|
64
|
+
|
|
65
|
+
| Not doing | Reason |
|
|
66
|
+
| --- | --- |
|
|
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` |
|
|
71
|
+
|
|
72
|
+
## Dual-layer architecture
|
|
73
|
+
|
|
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.
|
|
75
|
+
|
|
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.
|
|
77
|
+
|
|
78
|
+

|
|
79
|
+
|
|
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.
|
|
84
|
+
|
|
85
|
+
## Supervision loop
|
|
86
|
+
|
|
87
|
+

|
|
88
|
+
|
|
89
|
+
```text
|
|
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
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
## Install
|
|
103
|
+
|
|
104
|
+
Requires DSH `>=0.2.2-rc.3 <0.3.0-0` and Node `^22.19.0 || >=24`.
|
|
105
|
+
|
|
106
|
+
```bash
|
|
107
|
+
# install from npm into the current profile
|
|
108
|
+
dsh plugin --profile desktop add dsh-superagent-ptc
|
|
109
|
+
```
|
|
110
|
+
|
|
111
|
+
Restart DSH completely after installing, then create a session and pick **SuperAgent PTC** in the preset selector.
|
|
112
|
+
|
|
113
|
+
### Install through the DSH plugin market index
|
|
114
|
+
|
|
115
|
+
In DSH -> Settings -> Plugins -> Discover, add this index URL and search for `SuperAgent PTC`:
|
|
116
|
+
|
|
117
|
+
```text
|
|
118
|
+
https://raw.githubusercontent.com/BioAIEvolu/dsh-superagent-ptc/main/market-index.json
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
The index passes the official `parseMarketIndex` validation and resolves to the current npm release shown in the badge above.
|
|
122
|
+
|
|
123
|
+
### Local development install
|
|
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
|
+
## Quick start
|
|
131
|
+
|
|
132
|
+
1. Create a session and choose the **SuperAgent PTC** preset.
|
|
133
|
+
2. Describe the objective and the definition of done, for example:
|
|
134
|
+
|
|
135
|
+
```text
|
|
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.
|
|
141
|
+
```
|
|
142
|
+
|
|
143
|
+
3. Click **Super Agent supervision** above the composer; the right panel shows the live run and audit timeline.
|
|
144
|
+
|
|
145
|
+
## Tools
|
|
146
|
+
|
|
147
|
+
| Tool | Actions | Notes |
|
|
148
|
+
| --- | --- | --- |
|
|
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 |
|
|
156
|
+
|
|
157
|
+
Every write action carries `expectedRevision` and `expectedGeneration`; conflicts are rejected instead of silently overwritten.
|
|
158
|
+
|
|
159
|
+
## Right panel
|
|
160
|
+
|
|
161
|
+

|
|
162
|
+
|
|
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.
|
|
166
|
+
|
|
167
|
+
## Evidence gates and boundaries
|
|
168
|
+
|
|
169
|
+
| Rule | Behavior |
|
|
170
|
+
| --- | --- |
|
|
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 |
|
|
178
|
+
|
|
179
|
+
## Compatibility
|
|
180
|
+
|
|
181
|
+
| Item | Value |
|
|
182
|
+
| --- | --- |
|
|
183
|
+
| DSH | `>=0.2.2-rc.3 <0.3.0-0` (development baseline `0.2.2-rc.5`) |
|
|
184
|
+
| Node | `^22.19.0 || >=24.0.0` |
|
|
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` |
|
|
187
|
+
|
|
188
|
+
## Verification
|
|
189
|
+
|
|
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).
|
|
194
|
+
|
|
195
|
+
### Known unknown
|
|
196
|
+
|
|
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.
|
|
199
|
+
|
|
200
|
+
## FAQ
|
|
201
|
+
|
|
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.
|
|
204
|
+
|
|
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.
|
|
207
|
+
|
|
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.
|
|
210
|
+
|
|
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.
|
|
213
|
+
|
|
214
|
+
## Development
|
|
215
|
+
|
|
216
|
+
```bash
|
|
217
|
+
pnpm install
|
|
218
|
+
pnpm typecheck && pnpm build && pnpm test
|
|
219
|
+
```
|
|
220
|
+
|
|
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
|
|
224
|
+
|
|
225
|
+
## Acknowledgements
|
|
226
|
+
|
|
227
|
+
This plugin did not appear from thin air. It grew out of a real group discussion and source share on 2026-11-17:
|
|
228
|
+
|
|
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.
|
|
233
|
+
|
|
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).
|
|
235
|
+
|
|
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.
|
|
237
|
+
|
|
238
|
+
## License
|
|
239
|
+
|
|
240
|
+
MIT, see [LICENSE](LICENSE). Upstream DSH component notices are recorded in [NOTICE.md](NOTICE.md).
|
package/README.md
CHANGED
|
@@ -1,240 +1,240 @@
|
|
|
1
1
|
# SuperAgent PTC
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
[](README.en.md) [](README.md)
|
|
4
4
|
|
|
5
|
-
[](https://www.npmjs.com/package/dsh-superagent-ptc)
|
|
6
|
+
[](https://www.npmjs.com/package/dsh-superagent-ptc)
|
|
7
|
+
[](LICENSE)
|
|
8
8
|
[](https://github.com/deepseek-ai/deepseek-harness)
|
|
9
|
-
[](docs/VALIDATION.md)
|
|
10
10
|
|
|
11
|
-
> **
|
|
11
|
+
> **DeepSeek Harness 的长任务监督层**——版本化锚点、有界委派、独立验收、证据放行。
|
|
12
12
|
|
|
13
|
-
SuperAgent PTC
|
|
13
|
+
SuperAgent PTC 把“模型说自己做完了”变成“独立验收者证明它做完了”。它是 **preset-first** 插件:在原生 PTC / Agent / Goal / Teams 运行时之上叠加一层监管,不另造 Agent loop、任务板或路由器。
|
|
14
14
|
|
|
15
|
-
```
|
|
16
|
-
|
|
17
|
-
PTC
|
|
18
|
-
|
|
15
|
+
```text
|
|
16
|
+
你:把这份调研拆成三项工作,逐个验收后再写总结
|
|
17
|
+
PTC:Run + Anchor → 逐项 Mandate 派给 Worker → standard Reviewer 独立核验
|
|
18
|
+
→ 证据通过才放行 → super_snapshot 返回可验证的 revision 与 proof
|
|
19
19
|
```
|
|
20
20
|
|
|
21
|
-

|
|
22
22
|
|
|
23
|
-
##
|
|
23
|
+
## 目录
|
|
24
24
|
|
|
25
|
-
- [
|
|
26
|
-
- [
|
|
27
|
-
- [
|
|
28
|
-
- [
|
|
29
|
-
- [
|
|
30
|
-
- [
|
|
31
|
-
- [
|
|
32
|
-
- [
|
|
33
|
-
- [
|
|
34
|
-
- [
|
|
35
|
-
- [
|
|
36
|
-
- [
|
|
37
|
-
- [
|
|
38
|
-
- [
|
|
39
|
-
- [
|
|
25
|
+
- [为什么需要它](#为什么需要它)
|
|
26
|
+
- [特性](#特性)
|
|
27
|
+
- [双层架构](#双层架构)
|
|
28
|
+
- [监督循环](#监督循环)
|
|
29
|
+
- [安装](#安装)
|
|
30
|
+
- [快速上手](#快速上手)
|
|
31
|
+
- [工具](#工具)
|
|
32
|
+
- [右栏面板](#右栏面板)
|
|
33
|
+
- [证据门与边界](#证据门与边界)
|
|
34
|
+
- [兼容性](#兼容性)
|
|
35
|
+
- [验证](#验证)
|
|
36
|
+
- [常见问题](#常见问题)
|
|
37
|
+
- [开发](#开发)
|
|
38
|
+
- [致谢](#致谢)
|
|
39
|
+
- [许可](#许可)
|
|
40
40
|
|
|
41
|
-
##
|
|
41
|
+
## 为什么需要它
|
|
42
42
|
|
|
43
|
-
|
|
43
|
+
长任务失败通常不是“模型不会写”,而是四件事没有被约束:
|
|
44
44
|
|
|
45
|
-
|
|
|
45
|
+
| 常见问题 | 后果 | SuperAgent PTC 的做法 |
|
|
46
46
|
| --- | --- | --- |
|
|
47
|
-
|
|
|
48
|
-
|
|
|
49
|
-
|
|
|
50
|
-
|
|
|
47
|
+
| 目标在长对话里漂移 | 做到一半换了题目 | **版本化 Anchor**:目标、完成定义与义务都有版本,纠正会显式失效旧工作 |
|
|
48
|
+
| 模型自报完成 | “done” 却没有验证 | `reported_done ≠ accepted`,必须先过独立 Reviewer 与证据门 |
|
|
49
|
+
| 委派没有边界 | Worker 越权或重复劳动 | **Mandate 委派合同**:工作项、写域、模型路由与 attempt 在 prepare 时冻结 |
|
|
50
|
+
| 崩溃后状态不明 | 不知道哪里可信 | **SnapshotProof + RunState v2**:先写原生证明,再落存储,最后替换 live core |
|
|
51
51
|
|
|
52
|
-
##
|
|
52
|
+
## 特性
|
|
53
53
|
|
|
54
|
-
- **Preset-first
|
|
55
|
-
-
|
|
56
|
-
-
|
|
57
|
-
-
|
|
58
|
-
-
|
|
59
|
-
-
|
|
60
|
-
-
|
|
61
|
-
-
|
|
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
62
|
|
|
63
|
-
###
|
|
63
|
+
### 明确不做什么
|
|
64
64
|
|
|
65
|
-
|
|
|
65
|
+
| 不做 | 原因 |
|
|
66
66
|
| --- | --- |
|
|
67
|
-
|
|
|
68
|
-
|
|
|
69
|
-
|
|
|
70
|
-
|
|
|
67
|
+
| 不重建 Agent loop、任务板或全局路由 | 原生 Session、Agent、Goal、Teams 才是执行权威 |
|
|
68
|
+
| 不提供操作系统级文件权限沙箱 | 写域是协作契约,不是内核隔离 |
|
|
69
|
+
| 不做自动模型降级 | 只支持显式、白名单、预算内的有界故障切换 |
|
|
70
|
+
| 不把 `reported_done` 当作验收 | 只有独立 Reviewer 加证据门才产生 `accepted` |
|
|
71
71
|
|
|
72
|
-
##
|
|
72
|
+
## 双层架构
|
|
73
73
|
|
|
74
|
-
|
|
74
|
+
**一句话定位**:SuperAgent PTC 在宿主原生 Agent/Session 机制之上叠加一层监管状态机(`Run → Anchor → Mandate → Evidence → Decision`),把原生 agent 会话按角色(Lead / Worker / Reviewer)绑定进这条监管链;**PTC 的原生事件链**(`run_code` 调用与工具回执)**是整条链的证据底座**——监管层自己不产生第二套事件流。
|
|
75
75
|
|
|
76
|
-
|
|
76
|
+
监管面(Control Plane)只回答“能不能放行”,执行面(Execution Plane)只回答“实际做了什么”,两者之间只有一条契约膜:`super_*` 工具是状态与证据的唯一写入口。
|
|
77
77
|
|
|
78
|
-

|
|
79
79
|
|
|
80
|
-
- **A
|
|
81
|
-
-
|
|
82
|
-
- **B
|
|
83
|
-
-
|
|
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
84
|
|
|
85
|
-
##
|
|
85
|
+
## 监督循环
|
|
86
86
|
|
|
87
|
-

|
|
88
88
|
|
|
89
89
|
```text
|
|
90
|
-
super_run create #
|
|
91
|
-
super_run plan #
|
|
92
|
-
super_anchor #
|
|
93
|
-
super_mandate prepare #
|
|
94
|
-
super_mandate bind #
|
|
95
|
-
super_mandate bindReviewer #
|
|
96
|
-
super_evidence record #
|
|
97
|
-
super_review evaluate #
|
|
98
|
-
super_review decide/release #
|
|
99
|
-
super_snapshot #
|
|
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
100
|
```
|
|
101
101
|
|
|
102
|
-
##
|
|
102
|
+
## 安装
|
|
103
103
|
|
|
104
|
-
|
|
104
|
+
要求 DSH `>=0.2.2-rc.3 <0.3.0-0`,Node `^22.19.0 || >=24`。
|
|
105
105
|
|
|
106
106
|
```bash
|
|
107
|
-
#
|
|
107
|
+
# 从 npm 安装到当前 profile
|
|
108
108
|
dsh plugin --profile desktop add dsh-superagent-ptc
|
|
109
109
|
```
|
|
110
110
|
|
|
111
|
-
|
|
111
|
+
安装后**完全退出并重新启动 DSH**,然后新建会话,在预设选择器中选择 **SuperAgent PTC**。
|
|
112
112
|
|
|
113
|
-
###
|
|
113
|
+
### 通过 DSH 插件市场索引安装
|
|
114
114
|
|
|
115
|
-
|
|
115
|
+
在 DSH → 设置 → 插件 → 发现 中添加下面的索引 URL,然后搜索 `SuperAgent PTC`:
|
|
116
116
|
|
|
117
117
|
```text
|
|
118
118
|
https://raw.githubusercontent.com/BioAIEvolu/dsh-superagent-ptc/main/market-index.json
|
|
119
119
|
```
|
|
120
120
|
|
|
121
|
-
|
|
121
|
+
该索引已通过官方 `parseMarketIndex` 校验,解析为当前 npm 发布版本(与上方 npm 徽章一致)。
|
|
122
122
|
|
|
123
|
-
###
|
|
123
|
+
### 本地开发安装
|
|
124
124
|
|
|
125
125
|
```bash
|
|
126
126
|
git clone https://github.com/BioAIEvolu/dsh-superagent-ptc.git
|
|
127
127
|
dsh plugin --profile desktop add link:/absolute/path/to/dsh-superagent-ptc
|
|
128
128
|
```
|
|
129
129
|
|
|
130
|
-
##
|
|
130
|
+
## 快速上手
|
|
131
131
|
|
|
132
|
-
1.
|
|
133
|
-
2.
|
|
132
|
+
1. 新建会话,选择 **SuperAgent PTC** 预设。
|
|
133
|
+
2. 把目标与完成标准说清楚,例如:
|
|
134
134
|
|
|
135
135
|
```text
|
|
136
|
-
|
|
137
|
-
super_run create
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
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
141
|
```
|
|
142
142
|
|
|
143
|
-
3.
|
|
143
|
+
3. 点击 composer 上方的 **Super Agent 监管**,右栏会显示实时 Run 与审计时间线。
|
|
144
144
|
|
|
145
|
-
##
|
|
145
|
+
## 工具
|
|
146
146
|
|
|
147
|
-
|
|
|
147
|
+
| 工具 | 动作 | 说明 |
|
|
148
148
|
| --- | --- | --- |
|
|
149
|
-
| `super_run` | `create` `plan` `show` `recover` `complete` | Run
|
|
150
|
-
| `super_anchor` | `show` `apply` `history` |
|
|
151
|
-
| `super_mandate` | `prepare` `bind` `bindReviewer` `report` `show` |
|
|
152
|
-
| `super_evidence` | `record` `observe` `list` |
|
|
153
|
-
| `super_review` | `evaluate` `decide` `release` |
|
|
154
|
-
| `super_route` | `show` `set` `inspect` `switch` |
|
|
155
|
-
| `super_snapshot` | `{}` |
|
|
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
156
|
|
|
157
|
-
|
|
157
|
+
每个写动作都带 `expectedRevision` 与 `expectedGeneration`;冲突会被拒绝,而不是静默覆盖。
|
|
158
158
|
|
|
159
|
-
##
|
|
159
|
+
## 右栏面板
|
|
160
160
|
|
|
161
|
-

|
|
162
162
|
|
|
163
|
-
-
|
|
164
|
-
-
|
|
165
|
-
-
|
|
163
|
+
- 面板是**只读投影**:目标/Anchor、模型策略与路由审计、工作项、Mandate、证据与门禁、审计时间线、议程与 attempt。
|
|
164
|
+
- 面板不写状态;只有 `super_*` 工具能穿过 Host 的 CAS 校验修改状态。
|
|
165
|
+
- composer 入口不阻塞输入,普通会话看不到它。
|
|
166
166
|
|
|
167
|
-
##
|
|
167
|
+
## 证据门与边界
|
|
168
168
|
|
|
169
|
-
|
|
|
169
|
+
| 规则 | 行为 |
|
|
170
170
|
| --- | --- |
|
|
171
|
-
|
|
|
172
|
-
|
|
|
173
|
-
| Reviewer
|
|
174
|
-
|
|
|
175
|
-
|
|
|
176
|
-
|
|
|
177
|
-
|
|
|
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
178
|
|
|
179
|
-
##
|
|
179
|
+
## 兼容性
|
|
180
180
|
|
|
181
|
-
|
|
|
181
|
+
| 项 | 值 |
|
|
182
182
|
| --- | --- |
|
|
183
|
-
| DSH | `>=0.2.2-rc.3 <0.3.0-0
|
|
183
|
+
| DSH | `>=0.2.2-rc.3 <0.3.0-0`(开发基线 `0.2.2-rc.5`) |
|
|
184
184
|
| Node | `^22.19.0 || >=24.0.0` |
|
|
185
|
-
|
|
|
186
|
-
|
|
|
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
187
|
|
|
188
|
-
##
|
|
188
|
+
## 验证
|
|
189
189
|
|
|
190
|
-
-
|
|
191
|
-
-
|
|
192
|
-
-
|
|
193
|
-
-
|
|
190
|
+
- 自动化:**176 / 176 通过**;`typecheck` 与 `build` 均退出码 0。
|
|
191
|
+
- 真实桌面运行:两个独立 Electron 会话完成监督闭环,包含跨代恢复、多次 Anchor 修订、独立 Reviewer 放行与 SnapshotProof 对齐。
|
|
192
|
+
- 修复记录:Reviewer 只读守卫曾把 `pwsh "$env:NAME"` 判为写操作,现按参数分类并带回归测试。
|
|
193
|
+
- 细节见 [docs/VALIDATION.md](docs/VALIDATION.md)。
|
|
194
194
|
|
|
195
|
-
###
|
|
195
|
+
### 已知未知
|
|
196
196
|
|
|
197
|
-
-
|
|
198
|
-
-
|
|
197
|
+
- 真实 provider 故障切换、预算耗尽阻塞、`model.select` 失败分支从未在实机发生,保持 unknown。
|
|
198
|
+
- 不提供操作系统级文件沙箱,除会话隔离外没有额外安全边界。
|
|
199
199
|
|
|
200
|
-
##
|
|
200
|
+
## 常见问题
|
|
201
201
|
|
|
202
|
-
|
|
203
|
-
|
|
202
|
+
**选了预设但没有 `super_*` 工具?**
|
|
203
|
+
只有 `super-agent` 会话与已验证的只读 Reviewer 才有工具。确认预设确实切换,并完全重启 DSH。
|
|
204
204
|
|
|
205
|
-
**
|
|
206
|
-
|
|
205
|
+
**Reviewer 一直无法 decide?**
|
|
206
|
+
看门禁返回:`missingEvidence` / `staleEvidence` 需要补新证据;`REVIEWER_NOT_READONLY` 说明 Reviewer 产生过写回执,需要换一个全新的只读 Reviewer。
|
|
207
207
|
|
|
208
|
-
|
|
209
|
-
|
|
208
|
+
**崩溃后怎么恢复?**
|
|
209
|
+
root Lead 调用 `super_run recover`;generation 会增加,旧证据不复用,必须在新 generation 重新取证。
|
|
210
210
|
|
|
211
|
-
|
|
212
|
-
|
|
211
|
+
**能当全局路由或自动降级用吗?**
|
|
212
|
+
不能。`super_route` 只管理当前 Run 的显式策略,没有开箱即用的全局自动路由。
|
|
213
213
|
|
|
214
|
-
##
|
|
214
|
+
## 开发
|
|
215
215
|
|
|
216
216
|
```bash
|
|
217
217
|
pnpm install
|
|
218
218
|
pnpm typecheck && pnpm build && pnpm test
|
|
219
219
|
```
|
|
220
220
|
|
|
221
|
-
-
|
|
222
|
-
-
|
|
223
|
-
-
|
|
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
224
|
|
|
225
|
-
##
|
|
225
|
+
## 致谢
|
|
226
226
|
|
|
227
|
-
|
|
227
|
+
这个插件不是凭空想出来的,来自 2026-11-17 一次真实的群聊讨论与源码分享:
|
|
228
228
|
|
|
229
|
-
-
|
|
230
|
-
-
|
|
231
|
-
- **Electron
|
|
232
|
-
- **KOLA 2
|
|
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
233
|
|
|
234
|
-
|
|
234
|
+
同时感谢上游参考 `zouyuanqing/dsh-super-ptc-mode`(MIT):参考了其轻量 preset 组合与 Lead 委派理念,persona 与组合已按当前 DSH 契约重写,许可与出处保留在 [NOTICE.md](NOTICE.md)。
|
|
235
235
|
|
|
236
|
-
|
|
236
|
+
也感谢群里持续讨论、提问与纠正的每个人——这些对话让“证据放行”从一句口号变成了可验证的状态机。
|
|
237
237
|
|
|
238
|
-
##
|
|
238
|
+
## 许可
|
|
239
239
|
|
|
240
|
-
MIT
|
|
240
|
+
MIT,见 [LICENSE](LICENSE)。上游 DSH 组件声明记录在 [NOTICE.md](NOTICE.md)。
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "dsh-superagent-ptc",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.7",
|
|
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,7 +19,7 @@
|
|
|
19
19
|
"LICENSE",
|
|
20
20
|
"NOTICE.md",
|
|
21
21
|
"README.md",
|
|
22
|
-
"README.
|
|
22
|
+
"README.en.md",
|
|
23
23
|
"docs"
|
|
24
24
|
],
|
|
25
25
|
"engines": {
|
package/README.zh-CN.md
DELETED
|
@@ -1,240 +0,0 @@
|
|
|
1
|
-
# SuperAgent PTC
|
|
2
|
-
|
|
3
|
-
[英文](README.md) | **简体中文**
|
|
4
|
-
|
|
5
|
-
[](https://www.npmjs.com/package/dsh-superagent-ptc)
|
|
6
|
-
[](https://www.npmjs.com/package/dsh-superagent-ptc)
|
|
7
|
-
[](LICENSE)
|
|
8
|
-
[](https://github.com/deepseek-ai/deepseek-harness)
|
|
9
|
-
[](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
|
-

|
|
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
|
-

|
|
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
|
-

|
|
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
|
-

|
|
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)。
|