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 +141 -142
- package/README.zh-CN.md +240 -0
- package/docs/images/en/architecture-dual.png +0 -0
- package/docs/images/zh/architecture-dual.png +0 -0
- package/docs/images/zh/architecture-dual.svg +52 -0
- package/docs/images/zh/architecture-layers.png +0 -0
- package/docs/images/zh/architecture-layers.svg +60 -0
- package/docs/images/zh/lifecycle.png +0 -0
- package/docs/images/zh/lifecycle.svg +34 -0
- package/docs/images/zh/panel-mockup.png +0 -0
- package/docs/images/zh/panel-mockup.svg +33 -0
- package/package.json +2 -1
- package/docs/images/architecture-dual.png +0 -0
- /package/docs/images/{architecture-dual.svg → en/architecture-dual.svg} +0 -0
- /package/docs/images/{architecture-layers.png → en/architecture-layers.png} +0 -0
- /package/docs/images/{architecture-layers.svg → en/architecture-layers.svg} +0 -0
- /package/docs/images/{lifecycle.png → en/lifecycle.png} +0 -0
- /package/docs/images/{lifecycle.svg → en/lifecycle.svg} +0 -0
- /package/docs/images/{panel-mockup.png → en/panel-mockup.png} +0 -0
- /package/docs/images/{panel-mockup.svg → en/panel-mockup.svg} +0 -0
package/README.md
CHANGED
|
@@ -1,5 +1,7 @@
|
|
|
1
1
|
# SuperAgent PTC
|
|
2
2
|
|
|
3
|
+
**English** | [Chinese](README.zh-CN.md)
|
|
4
|
+
|
|
3
5
|
[](https://www.npmjs.com/package/dsh-superagent-ptc)
|
|
4
6
|
[](https://www.npmjs.com/package/dsh-superagent-ptc)
|
|
5
7
|
[](LICENSE)
|
|
@@ -7,235 +9,232 @@
|
|
|
7
9
|
[](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
|
-
|
|
17
|
-
|
|
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
|
-

|
|
21
|
+

|
|
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
|
-
|
|
|
45
|
+
| Problem | Consequence | What SuperAgent PTC does |
|
|
44
46
|
| --- | --- | --- |
|
|
45
|
-
|
|
|
46
|
-
|
|
|
47
|
-
|
|
|
48
|
-
|
|
|
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
|
|
53
|
-
-
|
|
54
|
-
-
|
|
55
|
-
-
|
|
56
|
-
-
|
|
57
|
-
-
|
|
58
|
-
-
|
|
59
|
-
-
|
|
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
|
-
|
|
|
66
|
-
|
|
|
67
|
-
|
|
|
68
|
-
|
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-

|
|
78
|
+

|
|
77
79
|
|
|
78
|
-
- **A
|
|
79
|
-
-
|
|
80
|
-
- **B
|
|
81
|
-
-
|
|
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
|
-

|
|
87
|
+

|
|
86
88
|
|
|
87
89
|
```text
|
|
88
|
-
super_run create #
|
|
89
|
-
super_run plan #
|
|
90
|
-
super_anchor #
|
|
91
|
-
super_mandate prepare #
|
|
92
|
-
super_mandate bind #
|
|
93
|
-
super_mandate bindReviewer #
|
|
94
|
-
super_evidence record #
|
|
95
|
-
super_review evaluate #
|
|
96
|
-
super_review decide/release #
|
|
97
|
-
super_snapshot #
|
|
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
|
-
|
|
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
|
|
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
|
-
|
|
111
|
+
Restart DSH completely after installing, then create a session and pick **SuperAgent PTC** in the preset selector.
|
|
113
112
|
|
|
114
|
-
###
|
|
113
|
+
### Install through the DSH plugin market index
|
|
115
114
|
|
|
116
|
-
|
|
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
|
-
|
|
121
|
+
The index passes the official `parseMarketIndex` validation and resolves to `dsh-superagent-ptc@0.1.3`.
|
|
123
122
|
|
|
124
|
-
|
|
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.
|
|
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
|
-
|
|
138
|
-
super_run create
|
|
139
|
-
Worker
|
|
140
|
-
prepare/bind/bindReviewer
|
|
141
|
-
|
|
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.
|
|
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
|
|
151
|
-
| `super_anchor` | `show` `apply` `history` |
|
|
152
|
-
| `super_mandate` | `prepare` `bind` `bindReviewer` `report` `show` |
|
|
153
|
-
| `super_evidence` | `record` `observe` `list` |
|
|
154
|
-
| `super_review` | `evaluate` `decide` `release` |
|
|
155
|
-
| `super_route` | `show` `set` `inspect` `switch` |
|
|
156
|
-
| `super_snapshot` | `{}` |
|
|
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
|
-
|
|
157
|
+
Every write action carries `expectedRevision` and `expectedGeneration`; conflicts are rejected instead of silently overwritten.
|
|
159
158
|
|
|
160
|
-
##
|
|
159
|
+
## Right panel
|
|
161
160
|
|
|
162
|
-

|
|
163
162
|
|
|
164
|
-
-
|
|
165
|
-
-
|
|
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
|
-
|
|
|
173
|
-
|
|
|
174
|
-
| Reviewer
|
|
175
|
-
|
|
|
176
|
-
|
|
|
177
|
-
|
|
|
178
|
-
|
|
|
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
|
|
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
|
-
|
|
|
187
|
-
|
|
|
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
|
-
-
|
|
192
|
-
-
|
|
193
|
-
-
|
|
194
|
-
-
|
|
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
|
-
-
|
|
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
|
-
**
|
|
204
|
-
|
|
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
|
-
**
|
|
207
|
-
|
|
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
|
-
**
|
|
210
|
-
root Lead
|
|
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
|
-
**
|
|
213
|
-
|
|
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
|
-
-
|
|
223
|
-
-
|
|
224
|
-
-
|
|
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
|
-
|
|
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
|
-
-
|
|
231
|
-
-
|
|
232
|
-
- **Electron
|
|
233
|
-
- **KOLA 2
|
|
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
|
-
|
|
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
|
|
240
|
+
MIT, see [LICENSE](LICENSE). Upstream DSH component notices are recorded in [NOTICE.md](NOTICE.md).
|
package/README.zh-CN.md
ADDED
|
@@ -0,0 +1,240 @@
|
|
|
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)。
|
|
Binary file
|
|
Binary file
|
|
@@ -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>
|
|
Binary file
|
|
@@ -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
|
+
"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
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|