From 9f5c552ae16bc919cb006fc5a24ca31ba7929823 Mon Sep 17 00:00:00 2001 From: Hunter Bown Date: Tue, 26 May 2026 10:26:54 -0500 Subject: [PATCH] =?UTF-8?q?docs:=20rewrite=20harness=20section=20=E2=80=94?= =?UTF-8?q?=20Constitution=20as=20jurisdiction,=20prefix-cache=20open-book?= =?UTF-8?q?=20test?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Replace the feature-grid format with a narrative that leads with the core problem the harness solves: conflicting information at scale. Frame the Constitution as a formal jurisdiction framework (LLM-as-judge), describe V4's prefix caching as what makes recursive constitutional reference practical (open-book test, not closed-book), and explain that the explicit authority structure enables honest failure feedback. Cut: memory/handoffs (table stakes), /statusline chip (internal), theme picker, desktop notifications (clutter). --- README.ja-JP.md | 20 ++++++++++--------- README.md | 53 ++++++++++++++++++++++++++++++++++++++++--------- README.zh-CN.md | 20 ++++++++++--------- 3 files changed, 66 insertions(+), 27 deletions(-) diff --git a/README.ja-JP.md b/README.ja-JP.md index f5db5dad..436d3a8c 100644 --- a/README.ja-JP.md +++ b/README.ja-JP.md @@ -71,23 +71,25 @@ DeepSeek V4 はこのハーネスの一部を書くのを手伝いました。 ### ハーネスの仕組み -**憲法的階層。** システムプロンプトは法の抵触エンジンです。ユーザーの意図は古いメモリより上。ライブの証拠は仮定より上。検証は自信より上。各ターンは明確な権限チェーンを継承するので、モデルはどの指示に従うべきか推測する必要がありません。 +エージェントモデルは大規模な相反する情報を扱います：ユーザーの意図、プロジェクトルール、システムデフォルト、ツール出力、古いメモリが単一ターンで権威を競い合います。LLM が裁判官として機能するには管轄権が必要です——衝突したとき、どの情報源が勝つのか？ -**構造化された信頼。** ハードな境界を持つ3つのモード——Plan（読み取り専用）、Agent（承認ゲート付き）、YOLO（信頼済みワークスペースで自動承認）。OS レベルのサンドボックスが境界を支えます。macOS Seatbelt はアクティブな適用パスです。Linux Landlock は検出されますが（カーネル 5.13+）現在は適用されていません。Windows サンドボックスはまだ公開されていません。危険なコマンドはモードに関係なく分類・ゲート制御されます。 +CodeWhale は**憲法**（`prompts/base.md`）でこれに答えます。これは形式化された法の階層です——第七条は憲法自体の条項から前セッションのハンドオフまで、9 つの情報源をランク付けします。ユーザーの現在のメッセージは古いプロジェクト指示より上。ライブのツール出力は仮定より上。検証は自信より上。モデルは毎ターン明確な権威チェーンを継承し、どの指示に従うべきか推測する必要がありません。 -**フィードバックの鼓動。** 失敗したコマンド、失敗したテスト、LSP 診断——これらは行き止まりではありません。モデルがチューニングできる信号です。非ゼロの終了コードは情報です。型エラーは修正ベクトルです。ハーネスは失敗を読み取り可能にし、ユーザーが常に舵を取り直さなくてもモデルが回復できるようにします。 +7 つの条項が階層の上にあり、モデルのアイデンティティ、義務、エージェンシーを定義します：検証義務（第5条——すべての行動は証拠を残し、信念で成功を宣言しない）、協調の遺産（第6条——次の知性のためにワークスペースを可読に保つ）、真実優先条項（第2条——下位のルールで上書きできない）。 -**継続性。** メモリはセッションをまたいで持続します。ハンドオフはコンテキスト圧縮後も生存します。セッションは保存・再開・兄弟パスへのフォークが可能です。次の知性——人間であれ機械であれ——が、すでに学ばれたことを再発見する必要なく、前回の中断点から引き継ぎます。 +DeepSeek V4 のプレフィックスキャッシュがこれを実用的にします。憲法は長く詳細ですが、一度キャッシュされるとコールドリードの約 100 分の 1 のコストになります。モデルはそれを再帰的に参照し——RLM セッションを通じて覗き、スキャンし、クエリし——単一の暗記パスに頼るのではなく、必要に応じて情報を再訪します。それは閉じた本のテストよりも、開いた本のテストのように機能します。 -**分散作業。** サブエージェントが並行実行、一度に最大 20。`agent_open` は即座に戻り、親は作業を続けます。結果は完了センチネルとしてインラインで到着し、サマリー付き。完全なトランスクリプトは `agent_eval` から取得可能な境界付きハンドルに保持されます。[docs/SUBAGENTS.md](docs/SUBAGENTS.md) を参照。 +権威構造が明示的であるため、失敗は隠されません。非ゼロの終了コード、ターン間に届く rust-analyzer からの型エラー、サンドボックス拒否——これらは修正ベクトルとしてフィードバックされます。モデルは自身のドリフトを使って自己修正します。 -**適正な知性。** Fin——thinking off の安価な Flash——がモデル自動ルーティング、RLM 子呼び出し、要約、調整を処理します。Pro はアーキテクチャ、デバッグ、セキュリティレビューに使用。`--model auto` がターンごとにモデルと思考レベルを選択します。各問題に適切な量の知性を。 +3 つのモードが行動空間を制御します。Plan は読み取り専用。Agent は破壊的操作を承認ゲートの背後に置きます。YOLO は信頼済みワークスペースで自動承認します。macOS Seatbelt はアクティブなサンドボックス；Linux Landlock は検出されるが未適用；Windows サンドボックスは未公開。 -**長期注意の経済学。** 100 万トークンのコンテキストウィンドウとプレフィックスキャッシュテレメトリ。キャッシュヒットはミスより約 100 倍安価。`/statusline` チップがプレフィックス安定性をリアルタイムで表示し、変更がキャッシュ予算を破壊しようとしているのが見えます。 +Fin——thinking off の安価な Flash 呼び出し——がターンごとにモデル自動ルーティングを処理します。`--model auto` がデフォルトです。 -**回復付きの自由。** 毎ターンの side-git スナップショット（リポジトリの `.git` には触れません）。`/restore` と `revert_turn` でワークスペースを即座にロールバック。危険な操作は OS レベルでサンドボックス化。モデルに試させることができます。 +毎ターン side-git スナップショットをリポジトリの `.git` 外に記録。`/restore` と `revert_turn` がワークスペースを即座にロールバックします。 -その他の機能面：**RLM セッション**（`peek`、`search`、`chunk`、`sub_query_batch` ヘルパー付きのバッチ分析用永続 Python REPL）、**LSP 診断**（編集ごとの rust-analyzer、pyright、tsserver、gopls、clangd からのインラインエラー）、**MCP プロトコル**、**HTTP/SSE ランタイム API**、再起動を超えて存続する**永続タスクキュー**、Zed や他のエディタ向け **ACP アダプター**、**SWE-bench エクスポート**、**インストール可能なスキル**、**テーマピッカー**、**デスクトップ通知**、キャッシュヒット/ミス内訳付きの**ライブコスト追跡**。 +サブエージェントは並行実行（最大 20）。`agent_open` は即座に戻り；結果は完了センチネルとしてインラインで到着し、サマリー付き。完全なトランスクリプトは `agent_eval` を通じて境界付きハンドルに保持されます。[docs/SUBAGENTS.md](docs/SUBAGENTS.md) を参照。 + +その他の機能面：編集ごとの LSP 診断（rust-analyzer、pyright、typescript-language-server、gopls、clangd）、バッチ分析用 RLM セッション、MCP プロトコル、HTTP/SSE ランタイム API、永続タスクキュー、Zed 向け ACP アダプター、SWE-bench エクスポート、キャッシュヒット/ミス内訳付きライブコスト追跡。 --- diff --git a/README.md b/README.md index 827e8975..6724c09b 100644 --- a/README.md +++ b/README.md @@ -83,23 +83,58 @@ DeepSeek V4 helped write parts of this harness. That matters because it means Co ### How the harness works -**Constitutional hierarchy.** The system prompt is a conflict-of-laws engine. User intent outranks stale memory. Live evidence outranks assumptions. Verification outranks confidence. Every turn inherits a clear chain of authority, so the model never has to guess which instruction to follow. +Agentic models deal with conflicting information at scale: user intent, +project rules, system defaults, tool output, and stale memory all compete +for authority in a single turn. LLM-as-a-judge needs jurisdiction — which +source wins when they disagree? -**Structured trust.** Three modes with hard boundaries — Plan (read-only), Agent (approval-gated), YOLO (auto-approved in trusted workspaces). OS-level sandboxing backs the boundaries: macOS Seatbelt is the active enforcement path. Linux Landlock support is detected (kernel 5.13+) but not yet enforced; Windows sandboxing is not yet advertised. Dangerous commands are classified and gated regardless of mode. +CodeWhale answers this with a **Constitution** (`prompts/base.md`). It's a +formal hierarchy of law — Article VII ranks nine sources from the +Constitution's own articles down to prior-session handoffs. The user's +current message outranks stale project instructions. Live tool output +outranks assumptions. Verification outranks confidence. The model inherits +a clear chain of authority every turn and never has to guess which +directive to follow. -**Feedback beats.** Failed commands, failing tests, LSP diagnostics — these are not dead ends. They are signals the model can tune against. A non-zero exit code is information. A type error is a correction vector. The harness makes failure legible so the model can recover without the user constantly re-steering. +Seven articles sit above the hierarchy, defining the model's identity, +duties, and agency: a verification mandate (Article V — every action leaves +evidence, never declare success on faith), a coordination legacy (Article +VI — leave the workspace legible for the next intelligence), and a +primacy-of-truth clause (Article II — no lower rule may override it). -**Continuity.** Memory persists across sessions. Handoffs survive context compaction. Sessions can be saved, resumed, and forked into sibling paths. The next intelligence — human or machine — picks up where the last one left off without having to re-discover what was already learned. +DeepSeek V4's prefix caching makes this practical. The Constitution is long +and detailed, but once cached it costs roughly 100× less per turn than a +cold read. The model references it recursively — peeking, scanning, and +querying through RLM sessions — revisiting information on demand rather +than relying on a single memorized pass. It performs more like an +open-book test than a closed one. -**Distributed work.** Sub-agents run concurrently, up to 20 at a time. `agent_open` returns immediately so the parent keeps working. Results arrive inline as completion sentinels with a summary; full transcripts stay behind bounded handles retrievable through `agent_eval`. See [docs/SUBAGENTS.md](docs/SUBAGENTS.md). +Because the authority structure is explicit, failure isn't hidden. Non-zero +exit codes, type errors from rust-analyzer arriving between turns, sandbox +denials — these are fed back as correction vectors. The model uses its own +drift to self-correct. -**Right-size intelligence.** Fin — cheap Flash with thinking off — handles model auto-routing, RLM child calls, summaries, and coordination. Pro engages for architecture, debugging, and security review. `--model auto` selects both the model and thinking level per turn. The right amount of intelligence for each problem. +Three modes control the action space. Plan is read-only. Agent gates +destructive operations behind approval. YOLO auto-approves in trusted +workspaces. macOS Seatbelt is the active sandbox; Linux Landlock is +detected but not yet enforced; Windows sandboxing is not yet advertised. -**Long-horizon attention economics.** 1M-token context window with prefix-cache telemetry. Cache hits cost roughly 100× less than misses. A `/statusline` chip shows prefix stability in real time so you can see when a change is about to bust the cache budget. +Fin — a cheap Flash call with thinking off — handles model auto-routing per +turn. `--model auto` is the default. -**Freedom with recovery.** Every turn records a side-git snapshot that doesn't touch your repo's `.git`. `/restore` and `revert_turn` roll back the workspace instantly. Dangerous operations are sandboxed at the OS level. You can let the model try things. +Every turn records a side-git snapshot outside your repo's `.git`. +`/restore` and `revert_turn` roll back the workspace. -The rest of the surface: **RLM sessions** (persistent Python REPL for batched analysis with `peek`, `search`, `chunk`, and `sub_query_batch` helpers), **LSP diagnostics** (inline errors from rust-analyzer, pyright, tsserver, gopls, clangd after every edit), **MCP protocol**, **HTTP/SSE runtime API**, **persistent task queue** that survives restarts, **ACP adapter** for Zed and other editors, **SWE-bench export**, **installable skills**, **theme picker**, **desktop notifications**, and **live cost tracking** with cache hit/miss breakdowns. +Sub-agents run concurrently (up to 20). `agent_open` returns immediately; +results arrive inline as completion sentinels with a summary. Full +transcripts stay behind bounded handles through `agent_eval`. See +[docs/SUBAGENTS.md](docs/SUBAGENTS.md). + +The rest of the surface: LSP diagnostics after every edit (rust-analyzer, +pyright, typescript-language-server, gopls, clangd), RLM sessions for +batched analysis, MCP protocol, HTTP/SSE runtime API, persistent task +queue, ACP adapter for Zed, SWE-bench export, and live cost tracking with +cache hit/miss breakdowns. --- diff --git a/README.zh-CN.md b/README.zh-CN.md index 1134887c..f46f4a8d 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -78,23 +78,25 @@ DeepSeek V4 参与了这套框架的部分编写。这很重要——它意味 ### 框架如何工作 -**宪政层级。** 系统提示词是一个冲突法引擎。用户意图优先于陈旧记忆。实时证据优先于假设。验证优先于自信。每一轮继承清晰的权威链，模型永远不需要猜测该服从哪条指令。 +智能体模型面临大规模的冲突信息：用户意图、项目规则、系统默认值、工具输出和陈旧记忆在单轮对话中争夺权威。LLM 作为裁判需要管辖权——当它们冲突时，哪个来源胜出？ -**结构化信任。** 三种模式，硬边界——Plan（只读）、Agent（审批门控）、YOLO（可信工作区自动批准）。OS 级沙箱支撑边界。macOS Seatbelt 是主动执行的沙箱路径。Linux Landlock 可被检测（内核 5.13+）但当前未实际执行；Windows 沙箱尚未开放。危险命令无论在哪种模式下都被分类和门控。 +CodeWhale 用一部**宪法**（`prompts/base.md`）来回答这个问题。它是一个形式化的法律层级——第七条将九个来源从宪法本身的条款排到前序会话的交接记录。用户当前消息优先于陈旧的项目指令。实时工具输出优先于假设。验证优先于自信。模型每轮继承清晰的权威链，永远不需要猜测该服从哪条指令。 -**反馈节拍。** 失败的命令、失败的测试、LSP 诊断——这些不是死胡同。它们是模型可以调谐的信号。非零退出码是信息。类型错误是修正向量。框架让失败变得可读，模型可以在用户不必不断重新掌舵的情况下恢复。 +七条条款位于层级之上，定义模型的身份、职责和能动性：验证强制（第五条——每个行动留下证据，绝不凭信念宣告成功）、协作遗产（第六条——让工作区对下一位智能体保持可读）、以及真相优先条款（第二条——任何下级规则不得覆盖它）。 -**连续性。** 记忆跨会话持久化。交接在上下文压缩后存活。会话可以保存、恢复和分叉到兄弟路径。下一位智能体——人或机器——从上一位置继续，无需重新发现已经学到的东西。 +DeepSeek V4 的前缀缓存使其可行。宪法篇幅长且详细，但一旦缓存，每轮成本约为冷读取的百分之一。模型递归引用它——通过 RLM 会话窥视、扫描和查询——按需重访信息，而非依赖单次记忆读取。它的表现更像是开卷考试而非闭卷考试。 -**分布式工作。** 子智能体并发运行，一次最多 20 个。`agent_open` 立即返回，父进程继续工作。结果以内联完成哨兵形式到达，携带摘要；完整对话记录可通过 `agent_eval` 的有界句柄读取。详见 [docs/SUBAGENTS.md](docs/SUBAGENTS.md)。 +因为权威结构是显式的，失败不会被隐藏。非零退出码、两次轮次间来自 rust-analyzer 的类型错误、沙箱拒绝——这些被作为修正向量反馈。模型用自己的漂移进行自我校正。 -**适度智能。** Fin——关闭思考的廉价 Flash——处理模型自动路由、RLM 子调用、摘要和协调。Pro 用于架构、调试和安全审查。`--model auto` 每轮选择模型和思考强度。每个问题匹配恰当的智能量。 +三种模式控制行动空间。Plan 只读。Agent 对破坏性操作设审批门控。YOLO 在可信工作区自动批准。macOS Seatbelt 是主动执行的沙箱；Linux Landlock 可检测但未执行；Windows 沙箱尚未开放。 -**长程注意力经济学。** 100 万 token 上下文窗口，前缀缓存遥测。缓存命中比未命中便宜约 100 倍。`/statusline` 芯片实时显示前缀稳定性，让你能看到某次变更是否即将破坏缓存预算。 +Fin——关闭思考的廉价 Flash 调用——每轮处理模型自动路由。`--model auto` 是默认值。 -**自由与恢复。** 每轮记录 side-git 快照，不影响仓库 `.git`。`/restore` 和 `revert_turn` 即刻回滚工作区。危险操作在 OS 级沙箱化。你可以让模型放手尝试。 +每轮记录 side-git 快照，在仓库 `.git` 之外。`/restore` 和 `revert_turn` 即刻回滚工作区。 -其余功能面：**RLM 会话**（持久化 Python REPL，配合 `peek`、`search`、`chunk`、`sub_query_batch` 辅助函数进行批量分析）、**LSP 诊断**（每次编辑后 rust-analyzer、pyright、tsserver、gopls、clangd 的内联错误）、**MCP 协议**、**HTTP/SSE 运行时 API**、重启后仍存活的**持久化任务队列**、Zed 等编辑器的 **ACP 适配器**、**SWE-bench 导出**、**可安装技能**、**主题选择器**、**桌面通知**、以及带缓存命中/未命中明细的**实时成本追踪**。 +子智能体并发运行（最多 20 个）。`agent_open` 立即返回；结果以内联完成哨兵形式到达，携带摘要。完整对话记录通过 `agent_eval` 的有界句柄保存。详见 [docs/SUBAGENTS.md](docs/SUBAGENTS.md)。 + +其余功能面：每次编辑后的 LSP 诊断（rust-analyzer、pyright、typescript-language-server、gopls、clangd）、RLM 会话批量分析、MCP 协议、HTTP/SSE 运行时 API、持久化任务队列、Zed 的 ACP 适配器、SWE-bench 导出、以及带缓存命中/未命中明细的实时成本追踪。 ---