proofdeck 0.1.0 → 0.1.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +95 -40
- package/README.zh-CN.md +96 -33
- package/bin/proofdeck.js +86 -21
- package/config.example.json +1 -0
- package/daemon.js +37 -1
- package/docs/assets/logo-512.png +0 -0
- package/docs/assets/logo.svg +31 -0
- package/docs/assets/social-preview.png +0 -0
- package/docs/render-logo.py +101 -0
- package/docs/task-book.md +58 -0
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,39 +1,67 @@
|
|
|
1
|
-
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
1
|
+
<div align="center">
|
|
2
|
+
<img src="docs/assets/logo.svg" width="150" alt="ProofDeck logo">
|
|
3
|
+
|
|
4
|
+
<h1>ProofDeck</h1>
|
|
5
|
+
|
|
6
|
+
<p><strong>Verification-first task board & orchestrator for coding-agent fleets.</strong><br>
|
|
7
|
+
<em>Agents claim done. ProofDeck demands proof.</em></p>
|
|
8
|
+
|
|
9
|
+
<p>
|
|
10
|
+
<a href="https://github.com/kumu314/proofdeck/actions/workflows/ci.yml"><img src="https://github.com/kumu314/proofdeck/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
|
|
11
|
+
<a href="https://www.npmjs.com/package/proofdeck"><img src="https://img.shields.io/npm/v/proofdeck.svg" alt="npm"></a>
|
|
12
|
+
<a href="./LICENSE"><img src="https://img.shields.io/badge/license-Apache--2.0-blue.svg" alt="license"></a>
|
|
13
|
+
<img src="https://img.shields.io/badge/node-%E2%89%A522.5-green.svg" alt="node ≥22.5">
|
|
14
|
+
<img src="https://img.shields.io/badge/platform-Windows%20%7C%20Linux-lightgrey.svg" alt="platform">
|
|
15
|
+
</p>
|
|
16
|
+
|
|
17
|
+
<p>
|
|
18
|
+
<a href="#quick-start">Quick start</a> ·
|
|
19
|
+
<a href="#why">Why</a> ·
|
|
20
|
+
<a href="#architecture">Architecture</a> ·
|
|
21
|
+
<a href="#the-five-check-families">Checks</a> ·
|
|
22
|
+
<a href="./README.zh-CN.md">中文文档</a>
|
|
23
|
+
</p>
|
|
24
|
+
</div>
|
|
25
|
+
|
|
26
|
+
<div align="center">
|
|
27
|
+
<img src="docs/assets/demo.gif" width="720" alt="A fake done gets rejected by the real verify engine">
|
|
28
|
+
<p><sub><b>The gate in 7 seconds:</b> an agent claims <i>done</i> on 1 item where acceptance said ≥3 — the real verify engine rejects it, the task returns to open, a verify event lands in the hash chain. Rendered from an actual run; nothing fabricated.</sub></p>
|
|
29
|
+
</div>
|
|
14
30
|
|
|
15
31
|
## Why
|
|
16
32
|
|
|
17
|
-
|
|
33
|
+
One coding agent (Claude Code, Codex CLI, Gemini CLI, …) → you review everything it does, and review works. **Several agents in parallel → review becomes the bottleneck**, and two failure modes compound:
|
|
18
34
|
|
|
19
|
-
|
|
20
|
-
|
|
35
|
+
| Failure mode | What it looks like | Industry context |
|
|
36
|
+
|---|---|---|
|
|
37
|
+
| **False affirmatives** | A fallback makes it "work"; tests pass; the flaw ships | *Reward hacking* — active research area (ImpossibleBench 2025, Anthropic 2026) |
|
|
38
|
+
| **Silent death** | Stalls, exits 0 with nothing done, burns budget in a loop | Nobody notices until the deadline |
|
|
21
39
|
|
|
22
|
-
ProofDeck's answer is to make **acceptance criteria a first-class column on every task** and
|
|
40
|
+
ProofDeck's answer is to make **acceptance criteria a first-class column on every task** and refuse "done" that lacks evidence — then wrap that gate in everything a fleet needs.
|
|
23
41
|
|
|
24
|
-
|
|
25
|
-
2. On completion, a fail-closed verification engine runs them (file existence, occurrence counts, JSON-path matches, reference existence — five check families).
|
|
26
|
-
3. An LLM judge reviews the trajectory against the criteria when machine checks are not enough; its verdict lands in an **append-only sha256 hash chain** next to who claimed the task, who verified it, and when.
|
|
27
|
-
4. Tasks that fail are retried with backoff, parked for human review, or routed to a different agent by capability — never silently marked done.
|
|
42
|
+
## The gate — how `done` gets proven
|
|
28
43
|
|
|
29
|
-
|
|
44
|
+
1. **Declare.** Every task carries machine-checkable acceptance criteria.
|
|
45
|
+
2. **Verify.** On completion a fail-closed engine runs them — five check families, unknown check types are FAIL, never skip.
|
|
46
|
+
3. **Judge.** When machine checks aren't enough, an LLM judge reviews the trajectory against the criteria.
|
|
47
|
+
4. **Record.** The verdict lands in an **append-only sha256 hash chain** — who claimed, who verified, when, with evidence.
|
|
48
|
+
5. **React.** Failed tasks retry with backoff, park for human review, or route to another agent by capability. Never silently done.
|
|
30
49
|
|
|
31
|
-
##
|
|
50
|
+
## Features
|
|
32
51
|
|
|
33
|
-
|
|
52
|
+
| Area | What you get |
|
|
53
|
+
|---|---|
|
|
54
|
+
| **Board** | Shared SQLite-backed task board with an MCP surface — any MCP-speaking agent reads/writes it |
|
|
55
|
+
| **Evidence** | Append-only sha256 chain over tasks/notes/messages/verify events; `verifyChain()` head anchoring |
|
|
56
|
+
| **Orchestration** | Priority lanes with aging · automatic retry with backoff · supply breaker · capability routing (`needs` × face capabilities) |
|
|
57
|
+
| **Judgment** | LLM judge (V1.5) with acceptance-only mode; human (V3) and cross-review (V2) escalation |
|
|
58
|
+
| **Observability** | Full event replay (time travel to any seq) · OpenTelemetry-style spans · per-run usage ledger |
|
|
59
|
+
| **Ops** | SLA due-dates · owner digest · leases · watchdog · offline-first (one SQLite file, no cloud) |
|
|
34
60
|
|
|
35
61
|
## Quick start
|
|
36
62
|
|
|
63
|
+
Requirements: **Node ≥ 22.5** (native `node:sqlite`; `better-sqlite3` fallback for older runtimes), Windows or Linux.
|
|
64
|
+
|
|
37
65
|
```bash
|
|
38
66
|
npx proofdeck init # scaffold: daemon.config.json + .proofdeck/ + control.token
|
|
39
67
|
# edit daemon.config.json — point agents.codex.script at a CLI you have
|
|
@@ -41,14 +69,17 @@ npx proofdeck daemon # start the daemon (board + control plane + scheduler)
|
|
|
41
69
|
npx proofdeck status # board head, task counts, acceptance coverage
|
|
42
70
|
```
|
|
43
71
|
|
|
44
|
-
From a git checkout
|
|
72
|
+
From a git checkout:
|
|
45
73
|
|
|
46
74
|
```bash
|
|
47
|
-
git clone https://github.com/kumu314/proofdeck && cd proofdeck
|
|
75
|
+
git clone https://github.com/kumu314/proofdeck && cd proofdeck
|
|
76
|
+
npm install # zero native module deps
|
|
48
77
|
node bin/proofdeck.js init && node bin/proofdeck.js daemon
|
|
49
78
|
```
|
|
50
79
|
|
|
51
|
-
Any agent that speaks MCP can read/write the board
|
|
80
|
+
Define a task with acceptance criteria, dispatch your agent, and watch the gate. Any agent that speaks MCP can read/write the board.
|
|
81
|
+
|
|
82
|
+
**Task books.** A task's instruction text lives in a file under `briefs/` with a small ```bridge fence carrying dispatch metadata (`auto`, `risk`, …); the card references it by path. The gate reads the book before dispatch — full format and gotchas in [docs/task-book.md](./docs/task-book.md).
|
|
52
83
|
|
|
53
84
|
## Architecture
|
|
54
85
|
|
|
@@ -67,32 +98,56 @@ Any agent that speaks MCP can read/write the board (tasks, notes, messages, veri
|
|
|
67
98
|
└───────────────────────────────────────────┘
|
|
68
99
|
```
|
|
69
100
|
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
101
|
+
| Component | File | Role |
|
|
102
|
+
|---|---|---|
|
|
103
|
+
| Board | `board/` | Vendored, modified [octopus-blackboard](https://github.com/octoryn/octopus-blackboard) fork — hash chain, MCP, acceptance/verification schema (see [NOTICE](./NOTICE)) |
|
|
104
|
+
| Verify engine | `lib/verify.js` | Fail-closed check runner, task-column-first acceptance |
|
|
105
|
+
| LLM judge | `lib/judge.js` | V1.5 trajectory review; unavailable judge fails open |
|
|
106
|
+
| Scheduler | `lib/schedule.js` | P0–P3 lanes, aging, retry policy (pure, unit-tested) |
|
|
107
|
+
| Routing | `lib/caps.js` | `needs` × face-capability matching |
|
|
108
|
+
| Replay | `lib/replay.js` | Fold timeline to any seq, diff against now |
|
|
109
|
+
| Platform | `lib/platform.js` | Dual-OS process primitives (killTree / getProcessInfo) |
|
|
110
|
+
| Adapters | `lib/adapters/` | One small module per agent face; `codex.js` is the reference implementation |
|
|
111
|
+
|
|
112
|
+
## The five check families
|
|
113
|
+
|
|
114
|
+
| Check | Asserts | Example |
|
|
115
|
+
|---|---|---|
|
|
116
|
+
| `fileExists` | File exists, ≥ `minBytes` | a rendered artifact actually shipped |
|
|
117
|
+
| `countAtLeast` | JSON value (number/array length) ≥ `min` | `report.count ≥ 3` |
|
|
118
|
+
| `countOccurrences` | Literal substring count ≥ `minCount` | changelog mentions the fix |
|
|
119
|
+
| `countMatches` | JSON-path match count ≥ `min` | every item has a status field |
|
|
120
|
+
| `referencesExist` | Files referenced in JSON exist | every asset in the manifest is on disk |
|
|
121
|
+
|
|
122
|
+
Unknown check types are **FAIL** — a typo in acceptance criteria never silently passes.
|
|
73
123
|
|
|
74
124
|
## Design principles
|
|
75
125
|
|
|
76
|
-
- **Fail closed.**
|
|
77
|
-
- **Evidence over vibes.** Verification results are
|
|
126
|
+
- **Fail closed.** Missing acceptance is flagged on every dispatch, never skipped.
|
|
127
|
+
- **Evidence over vibes.** Verification results are hash-chain events, not chat messages.
|
|
78
128
|
- **The board is the truth.** Agents come and go; the append-only timeline remembers.
|
|
79
|
-
- **Boring storage.** One SQLite file per deployment
|
|
129
|
+
- **Boring storage.** One SQLite file per deployment — no cloud, no telemetry.
|
|
130
|
+
- **Prompts via stdin, never argv.** Long CJK text corrupts through some shells (a production lesson).
|
|
80
131
|
|
|
81
132
|
## Testing
|
|
82
133
|
|
|
83
|
-
|
|
134
|
+
13 e2e suites run against real boards — verification, anti-fraud, judge, scheduling, resilience (watchdog/guard), replay, SLA/digest, lease, schema evolution:
|
|
84
135
|
|
|
85
136
|
```bash
|
|
86
|
-
|
|
137
|
+
npm test # native backend
|
|
138
|
+
OCTOBOARD_BACKEND=better-sqlite3 npm test # fallback backend
|
|
87
139
|
```
|
|
88
140
|
|
|
141
|
+
CI runs the full matrix on Windows + ubuntu, both backends — the native cell installs with `--omit=optional`, proving zero-native-dependency installs.
|
|
142
|
+
|
|
143
|
+
## Status
|
|
144
|
+
|
|
145
|
+
`v0.1.0`. Daily-production-proven on Windows (a personal multi-agent fleet, hundreds of tasks). Linux is CI-validated (13/13) with thinner real-world mileage — rough edges expected, reports welcome.
|
|
146
|
+
|
|
89
147
|
## Contributing & security
|
|
90
148
|
|
|
91
|
-
|
|
92
|
-
and evidence, same as our agents. Security disclosures via
|
|
93
|
-
[SECURITY.md](./SECURITY.md) (private reporting, 7-day response). Releases are
|
|
94
|
-
tagged; see [CHANGELOG.md](./CHANGELOG.md).
|
|
149
|
+
[CONTRIBUTING.md](./CONTRIBUTING.md) — PRs need CI green and pasted evidence, same standard as our agents. Security disclosures via [SECURITY.md](./SECURITY.md) (private reporting, 7-day response). Releases tagged — see [CHANGELOG.md](./CHANGELOG.md).
|
|
95
150
|
|
|
96
151
|
## License
|
|
97
152
|
|
|
98
|
-
Apache-2.0
|
|
153
|
+
[Apache-2.0](./LICENSE). Includes a modified distribution of [octopus-blackboard](https://github.com/octoryn/octopus-blackboard) by Ran Tao / octoryn — see [NOTICE](./NOTICE).
|
package/README.zh-CN.md
CHANGED
|
@@ -1,35 +1,67 @@
|
|
|
1
|
-
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
>
|
|
1
|
+
<div align="center">
|
|
2
|
+
<img src="docs/assets/logo.svg" width="150" alt="ProofDeck logo">
|
|
3
|
+
|
|
4
|
+
<h1>ProofDeck</h1>
|
|
5
|
+
|
|
6
|
+
<p><strong>验证优先的编码 agent 舰队任务板与编排器。</strong><br>
|
|
7
|
+
<em>Agent 说 done,ProofDeck 要证据。</em></p>
|
|
8
|
+
|
|
9
|
+
<p>
|
|
10
|
+
<a href="https://github.com/kumu314/proofdeck/actions/workflows/ci.yml"><img src="https://github.com/kumu314/proofdeck/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
|
|
11
|
+
<a href="https://www.npmjs.com/package/proofdeck"><img src="https://img.shields.io/npm/v/proofdeck.svg" alt="npm"></a>
|
|
12
|
+
<a href="./LICENSE"><img src="https://img.shields.io/badge/license-Apache--2.0-blue.svg" alt="license"></a>
|
|
13
|
+
<img src="https://img.shields.io/badge/node-%E2%89%A522.5-green.svg" alt="node ≥22.5">
|
|
14
|
+
<img src="https://img.shields.io/badge/platform-Windows%20%7C%20Linux-lightgrey.svg" alt="platform">
|
|
15
|
+
</p>
|
|
16
|
+
|
|
17
|
+
<p>
|
|
18
|
+
<a href="#快速开始">快速开始</a> ·
|
|
19
|
+
<a href="#为什么">为什么</a> ·
|
|
20
|
+
<a href="#架构">架构</a> ·
|
|
21
|
+
<a href="#五类检查族">检查族</a> ·
|
|
22
|
+
<a href="./README.md">English</a>
|
|
23
|
+
</p>
|
|
24
|
+
</div>
|
|
25
|
+
|
|
26
|
+
<div align="center">
|
|
27
|
+
<img src="docs/assets/demo.gif" width="720" alt="假完成被真实验证引擎当场拒绝">
|
|
28
|
+
<p><sub><b>7 秒看懂门禁:</b>agent 在验收要求 count≥3 的任务上只交付了 1 项就声称 <i>done</i>——真实验证引擎当场拒绝,任务退回 open 重新派发,验证事件落进哈希链。内容来自真实运行渲染,无任何虚构。</sub></p>
|
|
29
|
+
</div>
|
|
10
30
|
|
|
11
31
|
## 为什么
|
|
12
32
|
|
|
13
|
-
只跑一个编码 agent(Claude Code、Codex CLI、Gemini CLI……)时,你会 review 它的每一步,review
|
|
33
|
+
只跑一个编码 agent(Claude Code、Codex CLI、Gemini CLI……)时,你会 review 它的每一步,review 是有效的。但你一旦**并行跑好几个**,review 就成了瓶颈,两种失败模式叠加:
|
|
14
34
|
|
|
15
|
-
|
|
16
|
-
|
|
35
|
+
| 失败模式 | 典型表现 | 业界语境 |
|
|
36
|
+
|---|---|---|
|
|
37
|
+
| **虚假确认** | 加个 fallback 让代码"能跑",测试也过了,缺陷照样上线 | *reward hacking*——活跃研究课题(ImpossibleBench 2025、Anthropic 2026) |
|
|
38
|
+
| **静默死亡** | 卡住、rc=0 但什么都没干、预算烧进死循环 | 截止日期前没人发现 |
|
|
17
39
|
|
|
18
|
-
ProofDeck
|
|
40
|
+
ProofDeck 的答案是:**把验收标准做成每张任务的一等公民**,拒绝没有证据的"done"——再在这道门禁外面套上整支舰队需要的一切。
|
|
19
41
|
|
|
20
|
-
|
|
21
|
-
2. 完成时,fail-closed 验证引擎执行验收(文件存在、次数下限、JSON 路径断言、引用存在——五类检查);
|
|
22
|
-
3. 机器检查不够时,LLM judge 依据验收标准复核轨迹,它的判定连同"谁认领、谁验证、何时"一起写进**追加式 sha256 哈希链**;
|
|
23
|
-
4. 验证失败的任务按退避自动重试、转入人工复核、或按能力路由给另一个 agent——**绝不静默标记完成**。
|
|
42
|
+
## 门禁——"done" 如何被证明
|
|
24
43
|
|
|
25
|
-
|
|
44
|
+
1. **声明。** 每张任务携带机器可校验的验收标准。
|
|
45
|
+
2. **验证。** 完成时 fail-closed 引擎执行验收——五类检查,未知类型一律 FAIL,绝不跳过。
|
|
46
|
+
3. **复核。** 机器检查不够时,LLM judge 依据验收标准复核轨迹。
|
|
47
|
+
4. **记账。** 判定连同"谁认领、谁验证、何时"写进**追加式 sha256 哈希链**。
|
|
48
|
+
5. **响应。** 失败任务按退避重试、转人工复核、或按能力路由给其他 agent——绝不静默标记完成。
|
|
26
49
|
|
|
27
|
-
##
|
|
50
|
+
## 特性总览
|
|
28
51
|
|
|
29
|
-
|
|
52
|
+
| 领域 | 能力 |
|
|
53
|
+
|---|---|
|
|
54
|
+
| **黑板** | SQLite 共享任务板 + MCP 面——任何说 MCP 的 agent 可读写 |
|
|
55
|
+
| **证据** | 任务/注记/消息/验证事件的追加式 sha256 链;`verifyChain()` 锚定校验 |
|
|
56
|
+
| **编排** | 带 aging 的优先级车道 · 指数退避自动重试 · 供应熔断 · 能力路由(`needs` × 面能力) |
|
|
57
|
+
| **判定** | LLM judge(V1.5,acceptance-only 模式);人工(V3)与交叉评审(V2)升级 |
|
|
58
|
+
| **观测** | 全量事件回放(时间旅行到任意 seq)· OpenTelemetry 风格 span · 单轮用量台账 |
|
|
59
|
+
| **运维** | SLA 到期 · owner 摘要 · 租约 · 看门狗 · 离线优先(一个 SQLite 文件,无云依赖) |
|
|
30
60
|
|
|
31
61
|
## 快速开始
|
|
32
62
|
|
|
63
|
+
环境要求:**Node ≥ 22.5**(原生 `node:sqlite`;旧运行时用 `better-sqlite3` 回退),Windows 或 Linux。
|
|
64
|
+
|
|
33
65
|
```bash
|
|
34
66
|
npx proofdeck init # 脚手架:daemon.config.json + .proofdeck/ + control.token
|
|
35
67
|
# 编辑 daemon.config.json —— 把 agents.codex.script 指向你有的 CLI
|
|
@@ -40,11 +72,14 @@ npx proofdeck status # 看板块 head、任务统计、验收覆盖
|
|
|
40
72
|
从 git 检出运行:
|
|
41
73
|
|
|
42
74
|
```bash
|
|
43
|
-
git clone https://github.com/kumu314/proofdeck && cd proofdeck
|
|
75
|
+
git clone https://github.com/kumu314/proofdeck && cd proofdeck
|
|
76
|
+
npm install # 零原生模块依赖
|
|
44
77
|
node bin/proofdeck.js init && node bin/proofdeck.js daemon
|
|
45
78
|
```
|
|
46
79
|
|
|
47
|
-
|
|
80
|
+
给任务写上验收标准、派出你的 agent,然后看门禁工作。任何说 MCP 的 agent 都能读写黑板。
|
|
81
|
+
|
|
82
|
+
**任务书。** 任务的题面放在 `briefs/` 下的文件里,带一小段 ```bridge 围栏块承载派发元数据(`auto`、`risk`……),卡面只放文件指针。门禁在派发前会读任务书做风险评估——完整格式与坑位见 [docs/task-book.md](./docs/task-book.md)。
|
|
48
83
|
|
|
49
84
|
## 架构
|
|
50
85
|
|
|
@@ -62,28 +97,56 @@ node bin/proofdeck.js init && node bin/proofdeck.js daemon
|
|
|
62
97
|
└───────────────────────────────────────────┘
|
|
63
98
|
```
|
|
64
99
|
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
100
|
+
| 组件 | 文件 | 职责 |
|
|
101
|
+
|---|---|---|
|
|
102
|
+
| 黑板 | `board/` | [octopus-blackboard](https://github.com/octoryn/octopus-blackboard) 修改版发行——哈希链、MCP 面、验收/验证 schema(见 [NOTICE](./NOTICE)) |
|
|
103
|
+
| 验证引擎 | `lib/verify.js` | fail-closed 检查执行器,任务列优先的验收读取 |
|
|
104
|
+
| LLM judge | `lib/judge.js` | V1.5 轨迹复核;judge 不可用时优雅跳过 |
|
|
105
|
+
| 调度核 | `lib/schedule.js` | P0–P3 车道、aging、重试策略(纯函数、单测覆盖) |
|
|
106
|
+
| 路由 | `lib/caps.js` | `needs` × 面能力匹配 |
|
|
107
|
+
| 回放 | `lib/replay.js` | 折叠时间线到任意 seq,与当前态 diff |
|
|
108
|
+
| 平台 | `lib/platform.js` | 双 OS 进程原语(killTree / getProcessInfo) |
|
|
109
|
+
| 适配器 | `lib/adapters/` | 每个 agent 面一个小模块;`codex.js` 是参考实现 |
|
|
110
|
+
|
|
111
|
+
## 五类检查族
|
|
112
|
+
|
|
113
|
+
| 检查 | 断言 | 示例 |
|
|
114
|
+
|---|---|---|
|
|
115
|
+
| `fileExists` | 文件存在且 ≥ `minBytes` | 渲染产物真的出货了 |
|
|
116
|
+
| `countAtLeast` | JSON 值(数字/数组长度)≥ `min` | `report.count ≥ 3` |
|
|
117
|
+
| `countOccurrences` | 字面量子串出现次数 ≥ `minCount` | changelog 里提到了本次修复 |
|
|
118
|
+
| `countMatches` | JSON 路径匹配数 ≥ `min` | 每个条目都有 status 字段 |
|
|
119
|
+
| `referencesExist` | JSON 里引用的文件都存在 | manifest 里每个资产都在盘上 |
|
|
120
|
+
|
|
121
|
+
未知检查类型一律 **FAIL**——验收标准里的拼写错误永远不会静默放行。
|
|
68
122
|
|
|
69
123
|
## 设计原则
|
|
70
124
|
|
|
71
|
-
- **Fail closed。**
|
|
72
|
-
- **证据而非感觉。**
|
|
125
|
+
- **Fail closed。** 缺验收标准的任务每次派发都被标注提示,绝不静默跳过。
|
|
126
|
+
- **证据而非感觉。** 验证结果是哈希链事件,不是聊天记录。
|
|
73
127
|
- **黑板即真相。** Agent 来来去去;追加式时间线记得一切。
|
|
74
|
-
- **无聊的存储。** 每次部署一个 SQLite
|
|
128
|
+
- **无聊的存储。** 每次部署一个 SQLite 文件——无云、无遥测。
|
|
129
|
+
- **题面走 stdin,绝不走 argv。** 长中文文本过某些 shell 会被搅坏(生产线换来的教训)。
|
|
75
130
|
|
|
76
131
|
## 测试
|
|
77
132
|
|
|
78
|
-
13
|
|
133
|
+
13 套端到端套件打在真实黑板上——验证、防刷分、judge、调度、韧性(看门狗/guard)、回放、SLA/摘要、租约、schema 演进:
|
|
79
134
|
|
|
80
135
|
```bash
|
|
81
|
-
|
|
82
|
-
OCTOBOARD_BACKEND=better-sqlite3
|
|
136
|
+
npm test # 原生后端
|
|
137
|
+
OCTOBOARD_BACKEND=better-sqlite3 npm test # 回退后端
|
|
83
138
|
```
|
|
84
139
|
|
|
85
|
-
CI 在 Windows
|
|
140
|
+
CI 在 Windows + ubuntu × 双后端四格矩阵上跑全套;native 格用 `--omit=optional` 安装——在干净机器上实证"零原生依赖"。
|
|
141
|
+
|
|
142
|
+
## 状态
|
|
143
|
+
|
|
144
|
+
`v0.1.0`。Windows 上日常生产淬炼(个人多 agent 舰队,数百张任务)。Linux 已 CI 验证(13/13)但真实里程较薄——遇到坑请报 issue。
|
|
145
|
+
|
|
146
|
+
## 参与贡献与安全
|
|
147
|
+
|
|
148
|
+
[CONTRIBUTING.md](./CONTRIBUTING.md)——PR 需要 CI 绿 + 贴出证据,和我们的 agent 一个标准。安全披露走 [SECURITY.md](./SECURITY.md)(私有报告,7 天响应)。发版打 tag——见 [CHANGELOG.md](./CHANGELOG.md)。
|
|
86
149
|
|
|
87
150
|
## 许可
|
|
88
151
|
|
|
89
|
-
Apache-2.0
|
|
152
|
+
[Apache-2.0](./LICENSE)。含 [octopus-blackboard](https://github.com/octoryn/octopus-blackboard)(Ran Tao / octoryn)修改版发行——见 [NOTICE](./NOTICE)。
|
package/bin/proofdeck.js
CHANGED
|
@@ -14,6 +14,7 @@ import { join, dirname, resolve } from "node:path";
|
|
|
14
14
|
import { fileURLToPath } from "node:url";
|
|
15
15
|
import { spawn } from "node:child_process";
|
|
16
16
|
import { randomBytes } from "node:crypto";
|
|
17
|
+
import net from "node:net";
|
|
17
18
|
|
|
18
19
|
const PKG_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
|
|
19
20
|
const BOARD_PKG = join(PKG_ROOT, "board");
|
|
@@ -27,14 +28,24 @@ function usage() {
|
|
|
27
28
|
say(`ProofDeck — verification-first task board & orchestrator for coding-agent fleets
|
|
28
29
|
|
|
29
30
|
Usage:
|
|
30
|
-
proofdeck init [dir]
|
|
31
|
-
proofdeck daemon
|
|
32
|
-
proofdeck status
|
|
33
|
-
proofdeck
|
|
31
|
+
proofdeck init [dir] Scaffold a project dir (default: current)
|
|
32
|
+
proofdeck daemon Run the daemon for the current project dir
|
|
33
|
+
proofdeck status Show board head / task / verify counts
|
|
34
|
+
proofdeck assign <key> <agent> Queue a task card to an agent face
|
|
35
|
+
proofdeck --version Print version
|
|
34
36
|
|
|
35
37
|
Docs: https://github.com/kumu314/proofdeck`);
|
|
36
38
|
}
|
|
37
39
|
|
|
40
|
+
function findFreePort(start = 8790, tries = 20) {
|
|
41
|
+
return new Promise((res) => {
|
|
42
|
+
const srv = net.createServer();
|
|
43
|
+
srv.once("error", () => (tries-- > 0 ? res(findFreePort(start + 1, tries)) : res(start)));
|
|
44
|
+
srv.once("listening", () => srv.close(() => res(start)));
|
|
45
|
+
srv.listen(start, "127.0.0.1");
|
|
46
|
+
});
|
|
47
|
+
}
|
|
48
|
+
|
|
38
49
|
function cmdInit(args) {
|
|
39
50
|
const dir = resolve(args[0] ?? ".");
|
|
40
51
|
const cfgPath = join(dir, "daemon.config.json");
|
|
@@ -48,22 +59,75 @@ function cmdInit(args) {
|
|
|
48
59
|
// Point the vendored board at the packaged copy so init works from anywhere.
|
|
49
60
|
cfg.board.package = BOARD_PKG.replace(/\\/g, "/");
|
|
50
61
|
cfg.board.dir = "./.proofdeck";
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
const
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
62
|
+
|
|
63
|
+
// Per-face workdirs up front: agents spawn with -C <workdir>; a missing dir
|
|
64
|
+
// kills the face with os error 3 before it can say anything (dogfood finding).
|
|
65
|
+
const faces = Object.entries(cfg.agents ?? {});
|
|
66
|
+
for (const [name, face] of faces) {
|
|
67
|
+
if (face.workdir) face.workdir = join(dir, "workdirs", name).replace(/\\/g, "/");
|
|
68
|
+
}
|
|
69
|
+
|
|
70
|
+
// Free control-plane port: a fixed 8790 collides with any other ProofDeck on
|
|
71
|
+
// the machine (dogfood finding).
|
|
72
|
+
const port = findFreePort(cfg.http?.port ?? 8790);
|
|
73
|
+
return Promise.resolve(port).then((free) => {
|
|
74
|
+
if (cfg.http) cfg.http.port = free;
|
|
75
|
+
cfg.runtime ??= {};
|
|
76
|
+
cfg.runtime.autoAssign = true; // open+auto-flagged tasks queue to their face automatically
|
|
77
|
+
|
|
78
|
+
writeFileSync(cfgPath, JSON.stringify(cfg, null, 2) + "\n");
|
|
79
|
+
|
|
80
|
+
mkdirSync(join(dir, ".proofdeck"), { recursive: true });
|
|
81
|
+
mkdirSync(join(dir, "briefs"), { recursive: true });
|
|
82
|
+
for (const [name] of faces) mkdirSync(join(dir, "workdirs", name), { recursive: true });
|
|
83
|
+
const tokenPath = join(dir, "control.token");
|
|
84
|
+
if (!existsSync(tokenPath)) writeFileSync(tokenPath, randomBytes(24).toString("hex") + "\n");
|
|
85
|
+
|
|
86
|
+
// starter task book: the pointer-style brief with a ```bridge fence
|
|
87
|
+
const brief = join(dir, "briefs", "my-first-task.md");
|
|
88
|
+
if (!existsSync(brief)) {
|
|
89
|
+
writeFileSync(brief, [
|
|
90
|
+
"Write hello.md in the workspace containing the single line: it works.",
|
|
91
|
+
"",
|
|
92
|
+
"```bridge",
|
|
93
|
+
'{ "auto": "yes", "risk": "low", "impact": "low" }',
|
|
94
|
+
"```",
|
|
95
|
+
"",
|
|
96
|
+
].join("\n"));
|
|
97
|
+
}
|
|
98
|
+
|
|
99
|
+
ok(`scaffolded ${dir} (control port: ${free})`);
|
|
100
|
+
say(` daemon.config.json ← edit agents.* to point at your CLI(s)`);
|
|
101
|
+
say(` briefs/my-first-task.md ← starter task book (pointer-style)`);
|
|
102
|
+
say(` .proofdeck/ ← board lives here (one SQLite file + audit chain)`);
|
|
103
|
+
say(` control.token ← local control-plane credential`);
|
|
104
|
+
say("");
|
|
105
|
+
say("Next:");
|
|
106
|
+
say(" 1) edit daemon.config.json — set agents.codex.script to your agent CLI");
|
|
107
|
+
say(" 2) define the task card (see briefs/my-first-task.md + docs/task-book.md):");
|
|
108
|
+
say(` description: "任务书:${join(dir, "briefs", "my-first-task.md").replace(/\\\\/g, "/")}"`);
|
|
109
|
+
say(" 3) proofdeck daemon (or: node daemon.js daemon.config.json)");
|
|
110
|
+
say(" 4) proofdeck assign my-first-task codex — or let autoAssign queue it");
|
|
111
|
+
say(" 5) proofdeck status — watch the verify gate work");
|
|
112
|
+
return 0;
|
|
113
|
+
});
|
|
114
|
+
}
|
|
115
|
+
|
|
116
|
+
|
|
117
|
+
async function cmdAssign(args) {
|
|
118
|
+
const [key, agent] = args;
|
|
119
|
+
if (!key || !agent) { warn("usage: proofdeck assign <key> <agent>"); return 1; }
|
|
120
|
+
const cfgPath = join(process.cwd(), "daemon.config.json");
|
|
121
|
+
if (!existsSync(cfgPath)) { warn(`no daemon.config.json in ${process.cwd()}`); return 1; }
|
|
122
|
+
const cfg = JSON.parse(readFileSync(cfgPath, "utf8"));
|
|
123
|
+
const boardDir = resolve(process.cwd(), cfg.board.dir ?? ".proofdeck");
|
|
124
|
+
const pkg = cfg.board.package ?? BOARD_PKG;
|
|
125
|
+
const { Board } = await import(new URL("file://" + join(resolve(pkg), "dist", "board.js").replace(/\\/g, "/")).href);
|
|
126
|
+
const b = Board.open({ boardDir, agent: cfg.board.identity ?? "bridge" });
|
|
127
|
+
try {
|
|
128
|
+
b.assign(cfg.board.identity ?? "bridge", key, agent);
|
|
129
|
+
ok(`queued ${key} → ${agent}`);
|
|
130
|
+
} finally { try { b.close(); } catch { } }
|
|
67
131
|
return 0;
|
|
68
132
|
}
|
|
69
133
|
|
|
@@ -120,7 +184,8 @@ else if (cmd === "--version" || cmd === "-v") {
|
|
|
120
184
|
const pkg = JSON.parse(readFileSync(join(PKG_ROOT, "package.json"), "utf8"));
|
|
121
185
|
console.log(pkg.version);
|
|
122
186
|
process.exit(0);
|
|
123
|
-
} else if (cmd === "init") process.exit(cmdInit(rest));
|
|
187
|
+
} else if (cmd === "init") process.exit(await cmdInit(rest));
|
|
188
|
+
else if (cmd === "assign") process.exit(await cmdAssign(rest));
|
|
124
189
|
else if (cmd === "daemon") process.exit(await cmdDaemon());
|
|
125
190
|
else if (cmd === "status") process.exit(await cmdStatus());
|
|
126
191
|
else { warn(`unknown command: ${cmd}`); usage(); process.exit(1); }
|
package/config.example.json
CHANGED
package/daemon.js
CHANGED
|
@@ -3,7 +3,7 @@
|
|
|
3
3
|
// agent spawn -> automatic claim/progress/done/note write-back.
|
|
4
4
|
// Board I/O exclusively via the shared octopus-blackboard Board library.
|
|
5
5
|
import { readFileSync, writeFileSync, existsSync, mkdirSync, appendFileSync } from "node:fs";
|
|
6
|
-
import { join, dirname, resolve } from "node:path";
|
|
6
|
+
import { join, dirname, resolve, isAbsolute } from "node:path";
|
|
7
7
|
import { fileURLToPath } from "node:url";
|
|
8
8
|
import { spawn } from "node:child_process";
|
|
9
9
|
import { Worker } from "node:worker_threads";
|
|
@@ -38,6 +38,13 @@ const cfgPath = process.argv[2] ? resolveCfg(process.argv[2]) : join(BASE, "daem
|
|
|
38
38
|
function resolveCfg(p) { return p.includes(":") || p.startsWith("/") ? p : join(BASE, p); }
|
|
39
39
|
const cfg = JSON.parse(readFileSync(cfgPath, "utf8"));
|
|
40
40
|
|
|
41
|
+
// workdir absolutization: a relative workdir gets double-resolved through the
|
|
42
|
+
// spawn chain (daemon cwd → agent cwd) and dies with os error 3 before the
|
|
43
|
+
// face can say anything (dogfood finding). Normalize against BASE at load.
|
|
44
|
+
for (const face of Object.values(cfg.agents ?? {})) {
|
|
45
|
+
if (face.workdir && !isAbsolute(face.workdir)) face.workdir = resolve(BASE, face.workdir);
|
|
46
|
+
}
|
|
47
|
+
|
|
41
48
|
const ID = cfg.board.identity;
|
|
42
49
|
const DAY = () => { const d = new Date(); return `${d.getFullYear()}${String(d.getMonth() + 1).padStart(2, "0")}${String(d.getDate()).padStart(2, "0")}`; };
|
|
43
50
|
const LOGF = join(BASE, "logs", `daemon-${DAY()}.log`);
|
|
@@ -287,6 +294,35 @@ async function tick(why) {
|
|
|
287
294
|
}
|
|
288
295
|
store.save();
|
|
289
296
|
|
|
297
|
+
// 1.5) autoAssign(v0.1.1 上手路径修复):带 ```bridge auto 标记的 open 卡
|
|
298
|
+
// 无需手动 assign 事件——扫描后直接入队到第一个启用的面(gating 照常把关)。
|
|
299
|
+
// 关闭方式:runtime.autoAssign = false。
|
|
300
|
+
if (cfg.runtime?.autoAssign !== false) {
|
|
301
|
+
let auto = 0;
|
|
302
|
+
try {
|
|
303
|
+
await board.withBoard(cfg.board, (b) => {
|
|
304
|
+
for (const c of b.listTaskCards()) {
|
|
305
|
+
const t = c.task || {};
|
|
306
|
+
if (t.status !== "open") continue;
|
|
307
|
+
const key = t.key;
|
|
308
|
+
if (!key || store.s.runs[key] || store.s.finished[key] || store.s.pending[key]) continue;
|
|
309
|
+
if (Object.values(store.s.lanes ?? {}).some((l) => l.includes(key))) continue;
|
|
310
|
+
const fence = parseBridgeBlock(t.description ?? "");
|
|
311
|
+
if (!fence || !/^(yes|true|1)$/i.test(String(fence.auto ?? ""))) continue;
|
|
312
|
+
const agent = (enabledAgents.includes(fence.agent) && fence.agent) || enabledAgents[0];
|
|
313
|
+
if (!agent) continue;
|
|
314
|
+
if (store.queue(key, agent, { priority: fence.priority })) {
|
|
315
|
+
auto++;
|
|
316
|
+
log(`autoAssign ${key} -> ${agent} (fence auto flag)`);
|
|
317
|
+
}
|
|
318
|
+
}
|
|
319
|
+
});
|
|
320
|
+
} catch (e) {
|
|
321
|
+
log(`autoAssign scan error: ${e.message}`);
|
|
322
|
+
}
|
|
323
|
+
if (auto) store.save();
|
|
324
|
+
}
|
|
325
|
+
|
|
290
326
|
// 2) schedule lanes (paused entirely while STOP is present)
|
|
291
327
|
if (existsSync(STOP)) {
|
|
292
328
|
if (store.s.lanes && Object.values(store.s.lanes).some((l) => l.length)) log("STOP present — scheduling paused");
|
|
Binary file
|
|
@@ -0,0 +1,31 @@
|
|
|
1
|
+
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512" width="512" height="512">
|
|
2
|
+
<!-- ProofDeck logo: a deck card stamped with a proof seal, chained. -->
|
|
3
|
+
<defs>
|
|
4
|
+
<linearGradient id="cardbg" x1="0" y1="0" x2="1" y2="1">
|
|
5
|
+
<stop offset="0" stop-color="#1c2b2e"/>
|
|
6
|
+
<stop offset="1" stop-color="#172224"/>
|
|
7
|
+
</linearGradient>
|
|
8
|
+
</defs>
|
|
9
|
+
|
|
10
|
+
<!-- hash-chain dots leading into the card -->
|
|
11
|
+
<g fill="#a6d0b9" opacity="0.55">
|
|
12
|
+
<circle cx="70" cy="430" r="10"/>
|
|
13
|
+
<circle cx="108" cy="456" r="7"/>
|
|
14
|
+
<circle cx="142" cy="474" r="4.5"/>
|
|
15
|
+
</g>
|
|
16
|
+
|
|
17
|
+
<!-- the deck card, slightly stamped over -->
|
|
18
|
+
<g transform="rotate(-8 256 256)">
|
|
19
|
+
<rect x="96" y="96" width="320" height="320" rx="48" fill="url(#cardbg)" stroke="#e9c779" stroke-width="10"/>
|
|
20
|
+
<!-- proof seal: ring + check -->
|
|
21
|
+
<circle cx="256" cy="240" r="92" fill="none" stroke="#e9c779" stroke-width="12"/>
|
|
22
|
+
<circle cx="256" cy="240" r="74" fill="none" stroke="#a6d0b9" stroke-width="4" opacity="0.5"/>
|
|
23
|
+
<path d="M 214 244 L 246 276 L 306 204" fill="none" stroke="#a6d0b9" stroke-width="18" stroke-linecap="round" stroke-linejoin="round"/>
|
|
24
|
+
<!-- card footer rule: the "evidence line" -->
|
|
25
|
+
<line x1="170" y1="368" x2="342" y2="368" stroke="#e9c779" stroke-width="8" stroke-linecap="round" opacity="0.85"/>
|
|
26
|
+
<line x1="196" y1="388" x2="316" y2="388" stroke="#e9c779" stroke-width="5" stroke-linecap="round" opacity="0.45"/>
|
|
27
|
+
</g>
|
|
28
|
+
|
|
29
|
+
<!-- stamp notch: the deck was here -->
|
|
30
|
+
<circle cx="418" cy="118" r="9" fill="#e9c779" opacity="0.9"/>
|
|
31
|
+
</svg>
|
|
Binary file
|
|
@@ -0,0 +1,101 @@
|
|
|
1
|
+
#!/usr/bin/env python3
|
|
2
|
+
"""Render ProofDeck logo/social-preview PNGs (supersampled for crisp edges)."""
|
|
3
|
+
from PIL import Image, ImageDraw, ImageFont
|
|
4
|
+
import os
|
|
5
|
+
|
|
6
|
+
HERE = os.path.dirname(__file__)
|
|
7
|
+
ASSETS = os.path.join(HERE, "assets")
|
|
8
|
+
os.makedirs(ASSETS, exist_ok=True)
|
|
9
|
+
|
|
10
|
+
GOLD = (233, 199, 121)
|
|
11
|
+
MINT = (166, 208, 185)
|
|
12
|
+
CARD = (28, 43, 46)
|
|
13
|
+
CARD2 = (23, 34, 36)
|
|
14
|
+
BG = (16, 26, 27)
|
|
15
|
+
INK = (237, 240, 223)
|
|
16
|
+
DIM = (140, 158, 152)
|
|
17
|
+
|
|
18
|
+
def font(size, bold=True):
|
|
19
|
+
paths = (["C:/Windows/Fonts/segoeuib.ttf", "C:/Windows/Fonts/arialbd.ttf"] if bold
|
|
20
|
+
else ["C:/Windows/Fonts/segoeui.ttf", "C:/Windows/Fonts/arial.ttf"])
|
|
21
|
+
for p in paths:
|
|
22
|
+
if os.path.exists(p):
|
|
23
|
+
return ImageFont.truetype(p, size)
|
|
24
|
+
return ImageFont.load_default()
|
|
25
|
+
|
|
26
|
+
def rounded_card(d, cx, cy, size, rot_anti=False):
|
|
27
|
+
"""Draw the deck card (rotate applied on a square canvas via supersample coords)."""
|
|
28
|
+
# we draw axis-aligned here; rotation handled by drawing the whole logo rotated
|
|
29
|
+
half = size // 2
|
|
30
|
+
d.rounded_rectangle([cx - half, cy - half, cx + half, cy + half], radius=int(size * 0.15),
|
|
31
|
+
fill=CARD, outline=GOLD, width=10)
|
|
32
|
+
|
|
33
|
+
def seal(d, cx, cy, r):
|
|
34
|
+
d.ellipse([cx - r, cy - r, cx + r, cy + r], outline=GOLD, width=12)
|
|
35
|
+
r2 = r - 14
|
|
36
|
+
d.ellipse([cx - r2, cy - r2, cx + r2, cy + r2], outline=MINT, width=4)
|
|
37
|
+
# checkmark
|
|
38
|
+
pts = [(cx - r * 0.48, cy + r * 0.02), (cx - r * 0.12, cy + r * 0.42), (cx + r * 0.56, cy - r * 0.38)]
|
|
39
|
+
d.line(pts, fill=MINT, width=18, joint="curve")
|
|
40
|
+
for p in pts:
|
|
41
|
+
d.ellipse([p[0] - 9, p[1] - 9, p[0] + 9, p[1] + 9], fill=MINT)
|
|
42
|
+
|
|
43
|
+
def chain_dots(d, pts):
|
|
44
|
+
for (x, y, r, o) in pts:
|
|
45
|
+
c = MINT if o == 255 else (MINT[0], MINT[1], MINT[2])
|
|
46
|
+
d.ellipse([x - r, y - r, x + r, y + r], fill=(int(MINT[0] * o / 255), int(MINT[1] * o / 255), int(MINT[2] * o / 255)))
|
|
47
|
+
|
|
48
|
+
def draw_logo_square(scale=2, size_px=512):
|
|
49
|
+
S = size_px * scale
|
|
50
|
+
im = Image.new("RGBA", (S, S), (0, 0, 0, 0))
|
|
51
|
+
d = ImageDraw.Draw(im)
|
|
52
|
+
# rotate the whole emblem by drawing on a larger transparent canvas then rotating
|
|
53
|
+
emblem = Image.new("RGBA", (S, S), (0, 0, 0, 0))
|
|
54
|
+
ed = ImageDraw.Draw(emblem)
|
|
55
|
+
card_size = int(S * 0.62)
|
|
56
|
+
rounded_card(ed, S // 2, S // 2, card_size)
|
|
57
|
+
seal(ed, S // 2, int(S * 0.47), int(S * 0.18))
|
|
58
|
+
# evidence lines
|
|
59
|
+
ed.rounded_rectangle([int(S * 0.33), int(S * 0.72), int(S * 0.67), int(S * 0.745)],
|
|
60
|
+
radius=int(S * 0.012), fill=GOLD)
|
|
61
|
+
ed.rounded_rectangle([int(S * 0.38), int(S * 0.76), int(S * 0.62), int(S * 0.782)],
|
|
62
|
+
radius=int(S * 0.008), fill=(GOLD[0], GOLD[1], GOLD[2], 115))
|
|
63
|
+
# chain dots
|
|
64
|
+
chain_dots(ed, [(int(S * 0.14), int(S * 0.84), int(S * 0.02), 140),
|
|
65
|
+
(int(S * 0.21), int(S * 0.89), int(S * 0.014), 110),
|
|
66
|
+
(int(S * 0.27), int(S * 0.925), int(S * 0.009), 90)])
|
|
67
|
+
emblem = emblem.rotate(-8, resample=Image.BICUBIC, expand=False)
|
|
68
|
+
im.alpha_composite(emblem)
|
|
69
|
+
# gold notch
|
|
70
|
+
d.ellipse([int(S * 0.815), int(S * 0.2), int(S * 0.855), int(S * 0.24)], fill=GOLD)
|
|
71
|
+
return im.resize((size_px, size_px), Image.LANCZOS)
|
|
72
|
+
|
|
73
|
+
# 1) logo-512.png
|
|
74
|
+
logo = draw_logo_square(scale=2, size_px=512)
|
|
75
|
+
logo.save(os.path.join(ASSETS, "logo-512.png"))
|
|
76
|
+
|
|
77
|
+
# 2) social preview 1280x640
|
|
78
|
+
SPW, SPH = 1280, 640
|
|
79
|
+
S = 2
|
|
80
|
+
sp = Image.new("RGBA", (SPW * S, SPH * S), BG)
|
|
81
|
+
d = ImageDraw.Draw(sp)
|
|
82
|
+
# subtle vignette bands
|
|
83
|
+
for i, a in enumerate((18, 10)):
|
|
84
|
+
d.rounded_rectangle([40 * S + i * 22 * S, 40 * S + i * 22 * S, SPW * S - 40 * S - i * 22 * S, SPH * S - 40 * S - i * 22 * S],
|
|
85
|
+
radius=30 * S, outline=(GOLD[0], GOLD[1], GOLD[2], 0) if False else (46, 66, 68), width=3 * S)
|
|
86
|
+
logo_sq = draw_logo_square(scale=2, size_px=int(SPH * S * 0.78))
|
|
87
|
+
# paste logo at left
|
|
88
|
+
lx, ly = int(SPW * S * 0.06), int((SPH * S - logo_sq.height) // 2)
|
|
89
|
+
sp.alpha_composite(logo_sq, (lx, ly))
|
|
90
|
+
# wordmark
|
|
91
|
+
tx = lx + logo_sq.width + int(SPW * S * 0.055)
|
|
92
|
+
f_title = font(int(SPH * S * 0.17))
|
|
93
|
+
f_tag = font(int(SPH * S * 0.062), bold=False)
|
|
94
|
+
f_url = font(int(SPH * S * 0.042), bold=False)
|
|
95
|
+
d.text((tx, int(SPH * S * 0.24)), "ProofDeck", font=f_title, fill=INK)
|
|
96
|
+
d.text((tx + int(S * 6), int(SPH * S * 0.46)), "Agents claim done.", font=f_tag, fill=INK)
|
|
97
|
+
d.text((tx + int(S * 6), int(SPH * S * 0.545)), "ProofDeck demands proof.", font=f_tag, fill=MINT)
|
|
98
|
+
d.text((tx + int(S * 6), int(SPH * S * 0.72)), "github.com/kumu314/proofdeck", font=f_url, fill=DIM)
|
|
99
|
+
sp = sp.resize((SPW, SPH), Image.LANCZOS).convert("RGB")
|
|
100
|
+
sp.save(os.path.join(ASSETS, "social-preview.png"))
|
|
101
|
+
print("wrote", os.path.join(ASSETS, "logo-512.png"), "and", os.path.join(ASSETS, "social-preview.png"))
|
|
@@ -0,0 +1,58 @@
|
|
|
1
|
+
# Task books — how ProofDeck reads your tasks
|
|
2
|
+
|
|
3
|
+
A ProofDeck task has two halves:
|
|
4
|
+
|
|
5
|
+
1. **The card** on the board — title + a **pointer** to the task book file.
|
|
6
|
+
2. **The task book file** (under `briefs/`) — the actual instruction text plus a
|
|
7
|
+
```bridge fence carrying the dispatch metadata.
|
|
8
|
+
|
|
9
|
+
Why a file? The gating layer evaluates the book's content (risk words, sandbox
|
|
10
|
+
requests, auto flags) before dispatch, and the file is what gets archived with
|
|
11
|
+
the run for audit. Inline descriptions are treated as pointers only.
|
|
12
|
+
|
|
13
|
+
## Format
|
|
14
|
+
|
|
15
|
+
```markdown
|
|
16
|
+
<instruction text for the agent>
|
|
17
|
+
|
|
18
|
+
```bridge
|
|
19
|
+
{ "auto": "yes", "risk": "low", "impact": "low" }
|
|
20
|
+
```
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
The fence fields:
|
|
24
|
+
|
|
25
|
+
| Field | Meaning |
|
|
26
|
+
|---|---|
|
|
27
|
+
| `auto` | `"yes"` → the gate may dispatch automatically (risk words still apply) |
|
|
28
|
+
| `risk` | `low` / `medium` / `high` / `critical` — must be in `gating.autoRisk` for auto dispatch |
|
|
29
|
+
| `impact` | metadata; `high`/`critical` hits `gating.blockImpact` |
|
|
30
|
+
| `agent` | optional — pin the task to a specific face (otherwise first enabled face / autoAssign) |
|
|
31
|
+
| `priority` | optional — `P0`…`P3` lane priority |
|
|
32
|
+
| `acceptance` | optional — inline acceptance override (otherwise the card's `acceptance` column is used) |
|
|
33
|
+
| `sandbox` | optional — override the face sandbox for this task (`danger` requires approval) |
|
|
34
|
+
|
|
35
|
+
## Lifecycle
|
|
36
|
+
|
|
37
|
+
1. `proofdeck init` scaffolds `briefs/` with a starter task book.
|
|
38
|
+
2. Write the book, then put the pointer on a card:
|
|
39
|
+
`description: "任务书:D:/path/to/briefs/my-task.md"`
|
|
40
|
+
3. Dispatch it: `proofdeck assign my-task codex` — or just leave it open;
|
|
41
|
+
`autoAssign` (default on) queues auto-flagged books automatically.
|
|
42
|
+
4. The gate runs: risk words → auto/ask/soft; the face executes; the verify
|
|
43
|
+
engine checks acceptance; the verdict lands in the hash chain.
|
|
44
|
+
|
|
45
|
+
## Gotchas (dogfood-tested)
|
|
46
|
+
|
|
47
|
+
- **No fence → parked.** A book without a ```bridge fence is parked with
|
|
48
|
+
"未找到可读的任务书文件" — the gate refuses to guess your intent.
|
|
49
|
+
- **Relative `workdir` dies twice.** Face workdirs are resolved against the
|
|
50
|
+
daemon BASE at load; the agent's own `-C` resolves again inside the workdir —
|
|
51
|
+
use absolute paths (init normalizes them for you).
|
|
52
|
+
- **Codex faces need API-key mode for custom providers.** ChatGPT-account auth
|
|
53
|
+
only serves OpenAI models. Give a face its own `CODEX_HOME` with
|
|
54
|
+
`preferred_auth_method = "apikey"` + a DeepSeek/magpie provider to mix
|
|
55
|
+
account-quota and API-quota faces on one machine.
|
|
56
|
+
- **Windows sandbox blocks shell writes by default.** For tasks that must run
|
|
57
|
+
shell commands, set the face `sandbox` accordingly (`workspace-write` allows
|
|
58
|
+
workspace writes; anything broader is gated).
|
package/package.json
CHANGED