@tea-agent/loop-agent 0.35.0-beta.2 → 0.35.1-beta.0

package/docs/architecture/evolution.md

@@ -1,73 +1,73 @@
-# 架构演进：当前 vs 未来
-
-本页区分 loop-agent **当前已实现**的架构能力与**未来规划**。当前事实以代码、发布 CLI、已完成计划为准；未来能力一律标「规划 / 未实现 / 前瞻」。权威源：`CHANGELOG.md`、`docs/reports/current-capability-summary.md`、ADR 0001–0005、`docs/exec-plans/completed/` 与 `docs/exec-plans/active/`。
-
-**对照版本：`@tea-agent/loop-agent@0.24.0`（2026-07-27）**。细节版本条目见根 `CHANGELOG.md`；本表只保留架构层可读摘要。
-
-## 当前已实现（累计至 0.24.0）
-
-| 域 | 现状 | 权威入口 |
-| --- | --- | --- |
-| 受治理 Agent runtime | **Pi-only**；`cursor-prompt` 仅显式 one-shot sidecar | ADR 0001、`CHANGELOG.md [0.10.0]` |
-| Agent DAG 主链 | `dag run-task` → generate → validate → `run-dag`；report/doctor/reconcile-run | `dag-execution.md`、`test/cli-contract.test.ts` |
-| Dynamic Workflow | `WorkflowSpec` → validate → compile → 同一 `run-dag`；agent-like 节点仅 `pi\|static` | `src/workflows/dynamic/**`、`website/docs/guides/dynamic-workflow.md` |
-| 版本化自举 | controller identity + run-owned skill snapshot + deterministic canary | `docs/reports/feature/2026-07-13-versioned-self-hosting-bootstrap.md` |
-| Feature 交付（M2） | review/run/approve-followup/delivery/closeout/verify-final | `docs/reports/feature/2026-07-12-m2-completion-audit.md`、`CHANGELOG.md [0.10.0]` |
-| Task Pool | 唯一根 `.harness/task-pool/`；**feature-scoped** state v2（`TaskPoolTaskRef`） | ADR 0002、ADR 0004、`CHANGELOG.md [0.13.0]` |
-| Ready Planner | priority 选择；`batch plan-ready` 零写入；`run-ready` 冻结 plan；产物门禁 | `CHANGELOG.md [0.13.0]` / `[0.16.0]` |
-| TaskSpec → workflow | 可选 `execution.workflow` → `taskKind`；typed Outcome；`fullstack-v1` Verification Bundle | completed `2026-07-19-taskspec-workflow-routing.md`、`CHANGELOG.md [0.16.0]` |
-| 专用 taskKind DAG | `frontend-implementation` / `frontend-test` / `backend-test` / knowledge* | `website/docs/guides/agent-dag.md`、`CHANGELOG.md [0.12.0]`–`[0.17.x]` |
-| Backend-test | **Markdown-first 8 节点**；Markdown 映射限定 pytest 执行，生成 Markdown 与分层 HTML/脱敏请求响应详情 | completed `2026-07-24-backend-test-scoped-execution-report-ui.md`；`CHANGELOG.md [0.21.0]` / `[0.22.0]` |
-| Frontend-test | 默认 short-chain RAG；内容/evidence 质量进入 advisory findings，路径与安全边界仍 fail-closed | `CHANGELOG.md [0.21.0]` / `[0.22.0]` |
-| Frontend-implementation | Contract / trace / repair / Mock assess；`ai_workspace` + 知识库 + `openspec` 规范发现；lint 基线债务隔离 | `CHANGELOG.md [0.22.0]` |
-| Inspect（原 Observe） | 统一 Console 的 `/inspect/` 只读运营面与富时间线；独立 `observe serve` 已硬下线 | `website/docs/guides/observe-ui.md`、`CHANGELOG.md [Unreleased]` |
-| Local Operator Console | `agent-worker console\|doctor`（loopback；默认打开系统浏览器，`--no-open` 禁止）；Operate + Inspect、Happy Path / Interview / split view / recovery CTA；**0.23.x 起含 General Operator Chat**（Pi SDK services session、operator-only tool surface）；**非**远端多用户 Console | unify design；ADR 0005；completed `2026-07-25-console-phase-4-general-operator-chat.md` |
-| Task Contract / operator surface | journaled `task contract *`；machine envelope；**DagSpec v4 `taskContractBinding`**（exclusive writer 强制） | `CHANGELOG.md [0.17.0]`–`[0.17.2]`；ADR 0005 |
-| DagSpec / repair | v3 `runtimeContract` + 显式 `repairNodeId`；新 writer 生成默认 v4 binding | `dag-execution.md`、`CHANGELOG.md [0.11.0]` / `[0.17.0]` |
-| 自适应 liveness | runner lease、Provider/tool/output 活动与 meaningful progress 分离；静默 stall 受控终止，退出未确认时禁止自动重试 | `dag-execution.md`、active `2026-07-23-dag-adaptive-liveness.md` |
-| 运行恢复 | 节点内协议纠错重试、`dag rerun` 安全子图续跑、`dag rerun-task` 完整任务重跑与 Console Recovery | `CHANGELOG.md [0.20.1]`、active `2026-07-23-operator-rerun-hardening.md` |
-| Eval Lab | corpus / campaign / promote（人工门禁）；`autoPromote=false`；**非** RSI Level 1 | `CHANGELOG.md [0.15.0]`；active plan 可归档 |
-| 文档双树 | `website/docs/` 用法 vs `docs/` 治理；docs-converge | ADR 0003 |
-| 文档治理 | 任务式 Start Here、机器可读身份清单、目录默认身份与版本/索引语义检查 | 本目录 README、`docs/README.md`、`docs/document-catalog.json` |
-
-### 受治理 runtime 的边界（已实现、不变式）
-
-- DAG writer 固定 `implement-pi` / `repair-pi`；`executor: "cursor"`、`implement-cursor` / `repair-cursor`、Cursor worker、`cursor-fix` 已从受治理路径移除。
-- 完成权威 = shell verification；model verdict / Observe / 报告是 derived/advisory。
-- Worker 通过已发布 `loop-agent` 子进程执行，不 in-process import runtime kernel（governance 机器校验）。
-- Console / Compatibility 主会话不得绕过 CLI 直接改业务实现（ADR 0005）。
-
-## 未来规划（第 3–6 月，**未实现**）
-
-以下能力来自 `docs/design/active/六个月规划.md` 与相关设计输入（页首校准条之后的未交付 phase 为**设计输入**）。它们**当前不存在于产品声称的线上形态**，或仅有本地/部分替代：
-
-| 未来方向 | 状态 | 规划来源 |
-| --- | --- | --- |
-| 远程 PR / CI 自动创建与写回 | 规划 / 未实现 | `docs/design/active/六个月规划.md`（第 3 个月起） |
-| 线上 / 云 Worker | 规划 / 未实现 | 同上 |
-| 云 Task Pool / SQL / Orchestrator | 规划 / 未实现 | 同上（第 2 月原始设计已调整为本地 Feature 闭环） |
-| 多仓库平台 | 规划 / 未实现 | 同上 |
-| 组织级服务 | 规划 / 未实现 | 同上 |
-| Web Console（远端多用户） | 规划 / 未实现；**不等于**已发布的本地 loopback Operator Console | 同上；对照 `docs/design/archive/2026-07-21-local-operator-console-from-pi-web.md` |
-| fullstack Delivery / Final Verification live 闭环 | 进行中（active train） | `docs/exec-plans/active/2026-07-19-fullstack-dogfood-016x-release-train.md` |
-| Dynamic Workflow runtime limits 强执法、更广 profile | 设计输入 | `docs/design/active/dynamic-workflow-dag-engine-roadmap.md` |
-| Loop 与 Dynamic Workflow 更深双向集成 / 自动恢复 | 设计输入 | 同上；当前已有基础 `workflow` action |
-| Operator Chat 作为主操作会话（裸 bash 收敛、真 human gate、durable session/turn、Operation 闭环、完整 CLI action coverage、默认入口切换） | 设计输入 / 未达主会话门槛 | `docs/design/active/operator-chat-primary-session-roadmap.md`；Phase 4 General Operator Chat 本体已实现归档（`docs/exec-plans/completed/2026-07-25-console-phase-4-general-operator-chat.md`） |
-| Eval Lab auto-promote / RSI Level 1 产品声称 | **禁止**写成已交付 | Eval Lab design + active plan |
-
-> 本地 Operator Console 统一面（实际首发 0.19.0）已发布：单仓库、loopback、随 `@tea-agent/loop-agent` 同包、canonical mutation 只经 sibling CLI，Inspect 复用 GET-only Observe read model。它不是远端 Web Console，也不能把多租户/云编排需求偷渡进本地 Console。
-
-> 注意：`docs/design/active/dynamic-workflow-dag-engine-roadmap.md` 含 2026-07-04 历史叙述；文中凡把 Cursor 写成受治理 executor 或 `loop` 的 `cursor-fix` 动作，均为**历史叙述**，现状以 Pi-only + 显式 `cursor-prompt` sidecar 为准。
-
-## 已收敛为 archive / 历史基线（非未来）
-
-- 第 1–2 月规划已收敛为 archive/reports 指针，不在本文展开：`docs/design/archive/2026-07-12-第二月规划.md`。
-- `docs/reports/2026-07-02-repository-analysis.md` 自 2026-07-14 起冻结为**历史基线快照**（允许有限再采样），不当第二 CHANGELOG。
-- 活能力短摘要在 `docs/reports/current-capability-summary.md`。
-- 专题证据按类型落在 `docs/reports/{feature,init-evolution,merge,fullstack-dogfood,dogfood}/`。
-
-## 文档本体的演进边界
-
-- 本目录新增文档随发布包发布（`package.json` `files` + manifest `packageRequired` 显式条目），但 **不**投影到目标项目 init surface；目标项目 init 仍只投影语言无关的 `runtime-boundaries.md`。
-- `runtime-boundaries.md` 是边界真源；本目录其他文档交叉引用，不复制其 import 方向表 / governance-hook 表 / 版本化自举边界表。
-- 未来如有能力落地，应先改 `src/` / CLI / ADR / completed plan，再回写本目录的「已实现」表与站上 `website/docs/overview/*` 短索引。
+# 架构演进：当前 vs 未来
+
+本页区分 loop-agent **当前已实现**的架构能力与**未来规划**。当前事实以代码、发布 CLI、已完成计划为准；未来能力一律标「规划 / 未实现 / 前瞻」。权威源：`CHANGELOG.md`、`docs/reports/current-capability-summary.md`、ADR 0001–0005、`docs/exec-plans/completed/` 与 `docs/exec-plans/active/`。
+
+**对照版本：`@tea-agent/loop-agent@0.24.0`（2026-07-27）**。细节版本条目见根 `CHANGELOG.md`；本表只保留架构层可读摘要。
+
+## 当前已实现（累计至 0.24.0）
+
+| 域 | 现状 | 权威入口 |
+| --- | --- | --- |
+| 受治理 Agent runtime | **Pi-only**；`cursor-prompt` 仅显式 one-shot sidecar | ADR 0001、`CHANGELOG.md [0.10.0]` |
+| Agent DAG 主链 | `dag run-task` → generate → validate → `run-dag`；report/doctor/reconcile-run | `dag-execution.md`、`test/cli-contract.test.ts` |
+| Dynamic Workflow | `WorkflowSpec` → validate → compile → 同一 `run-dag`；agent-like 节点仅 `pi\|static` | `src/workflows/dynamic/**`、`website/docs/guides/dynamic-workflow.md` |
+| 版本化自举 | controller identity + run-owned skill snapshot + deterministic canary | `docs/reports/feature/2026-07-13-versioned-self-hosting-bootstrap.md` |
+| Feature 交付（M2） | review/run/approve-followup/delivery/closeout/verify-final | `docs/reports/feature/2026-07-12-m2-completion-audit.md`、`CHANGELOG.md [0.10.0]` |
+| Task Pool | 唯一根 `.harness/task-pool/`；**feature-scoped** state v2（`TaskPoolTaskRef`） | ADR 0002、ADR 0004、`CHANGELOG.md [0.13.0]` |
+| Ready Planner | priority 选择；`batch plan-ready` 零写入；`run-ready` 冻结 plan；产物门禁 | `CHANGELOG.md [0.13.0]` / `[0.16.0]` |
+| TaskSpec → workflow | 可选 `execution.workflow` → `taskKind`；typed Outcome；`fullstack-v1` Verification Bundle | completed `2026-07-19-taskspec-workflow-routing.md`、`CHANGELOG.md [0.16.0]` |
+| 专用 taskKind DAG | `frontend-implementation` / `frontend-test` / `backend-test` / knowledge* | `website/docs/guides/agent-dag.md`、`CHANGELOG.md [0.12.0]`–`[0.17.x]` |
+| Backend-test | **Markdown-first 8 节点**；Markdown 映射限定 pytest 执行，生成 Markdown 与分层 HTML/脱敏请求响应详情 | completed `2026-07-24-backend-test-scoped-execution-report-ui.md`；`CHANGELOG.md [0.21.0]` / `[0.22.0]` |
+| Frontend-test | 默认 short-chain RAG；内容/evidence 质量进入 advisory findings，路径与安全边界仍 fail-closed | `CHANGELOG.md [0.21.0]` / `[0.22.0]` |
+| Frontend-implementation | Contract / trace / repair / Mock assess；`ai_workspace` + 知识库 + `openspec` 规范发现；lint 基线债务隔离 | `CHANGELOG.md [0.22.0]` |
+| Inspect（原 Observe） | 统一 Console 的 `/inspect/` 只读运营面与富时间线；独立 `observe serve` 已硬下线 | `website/docs/guides/observe-ui.md`、`CHANGELOG.md [Unreleased]` |
+| Local Operator Console | `agent-worker console\|doctor`（loopback；默认打开系统浏览器，`--no-open` 禁止）；Operate + Inspect、Happy Path / Interview / split view / recovery CTA；**0.23.x 起含 General Operator Chat**（Pi SDK services session、operator-only tool surface）；**非**远端多用户 Console | unify design；ADR 0005；completed `2026-07-25-console-phase-4-general-operator-chat.md` |
+| Task Contract / operator surface | journaled `task contract *`；machine envelope；**DagSpec v4 `taskContractBinding`**（exclusive writer 强制） | `CHANGELOG.md [0.17.0]`–`[0.17.2]`；ADR 0005 |
+| DagSpec / repair | v3 `runtimeContract` + 显式 `repairNodeId`；新 writer 生成默认 v4 binding | `dag-execution.md`、`CHANGELOG.md [0.11.0]` / `[0.17.0]` |
+| 自适应 liveness | runner lease、Provider/tool/output 活动与 meaningful progress 分离；静默 stall 受控终止，退出未确认时禁止自动重试 | `dag-execution.md`、active `2026-07-23-dag-adaptive-liveness.md` |
+| 运行恢复 | 节点内协议纠错重试、`dag rerun` 安全子图续跑、`dag rerun-task` 完整任务重跑与 Console Recovery | `CHANGELOG.md [0.20.1]`、active `2026-07-23-operator-rerun-hardening.md` |
+| Eval Lab | corpus / campaign / promote（人工门禁）；`autoPromote=false`；**非** RSI Level 1 | `CHANGELOG.md [0.15.0]`；active plan 可归档 |
+| 文档双树 | `website/docs/` 用法 vs `docs/` 治理；docs-converge | ADR 0003 |
+| 文档治理 | 任务式 Start Here、机器可读身份清单、目录默认身份与版本/索引语义检查 | 本目录 README、`docs/README.md`、`docs/document-catalog.json` |
+
+### 受治理 runtime 的边界（已实现、不变式）
+
+- DAG writer 固定 `implement-pi` / `repair-pi`；`executor: "cursor"`、`implement-cursor` / `repair-cursor`、Cursor worker、`cursor-fix` 已从受治理路径移除。
+- 完成权威 = shell verification；model verdict / Observe / 报告是 derived/advisory。
+- Worker 通过已发布 `loop-agent` 子进程执行，不 in-process import runtime kernel（governance 机器校验）。
+- Console / Compatibility 主会话不得绕过 CLI 直接改业务实现（ADR 0005）。
+
+## 未来规划（第 3–6 月，**未实现**）
+
+以下能力来自 `docs/design/active/六个月规划.md` 与相关设计输入（页首校准条之后的未交付 phase 为**设计输入**）。它们**当前不存在于产品声称的线上形态**，或仅有本地/部分替代：
+
+| 未来方向 | 状态 | 规划来源 |
+| --- | --- | --- |
+| 远程 PR / CI 自动创建与写回 | 规划 / 未实现 | `docs/design/active/六个月规划.md`（第 3 个月起） |
+| 线上 / 云 Worker | 规划 / 未实现 | 同上 |
+| 云 Task Pool / SQL / Orchestrator | 规划 / 未实现 | 同上（第 2 月原始设计已调整为本地 Feature 闭环） |
+| 多仓库平台 | 规划 / 未实现 | 同上 |
+| 组织级服务 | 规划 / 未实现 | 同上 |
+| Web Console（远端多用户） | 规划 / 未实现；**不等于**已发布的本地 loopback Operator Console | 同上；对照 `docs/design/archive/2026-07-21-local-operator-console-from-pi-web.md` |
+| fullstack Delivery / Final Verification live 闭环 | 进行中（active train） | `docs/exec-plans/active/2026-07-19-fullstack-dogfood-016x-release-train.md` |
+| Dynamic Workflow runtime limits 强执法、更广 profile | 设计输入 | `docs/design/active/dynamic-workflow-dag-engine-roadmap.md` |
+| Loop 与 Dynamic Workflow 更深双向集成 / 自动恢复 | 设计输入 | 同上；当前已有基础 `workflow` action |
+| Operator Chat 作为主操作会话（裸 bash 收敛、真 human gate、durable session/turn、Operation 闭环、完整 CLI action coverage、默认入口切换） | 设计输入 / 未达主会话门槛 | `docs/design/active/operator-chat-primary-session-roadmap.md`；Phase 4 General Operator Chat 本体已实现归档（`docs/exec-plans/completed/2026-07-25-console-phase-4-general-operator-chat.md`） |
+| Eval Lab auto-promote / RSI Level 1 产品声称 | **禁止**写成已交付 | Eval Lab design + active plan |
+
+> 本地 Operator Console 统一面（实际首发 0.19.0）已发布：单仓库、loopback、随 `@tea-agent/loop-agent` 同包、canonical mutation 只经 sibling CLI，Inspect 复用 GET-only Observe read model。它不是远端 Web Console，也不能把多租户/云编排需求偷渡进本地 Console。
+
+> 注意：`docs/design/active/dynamic-workflow-dag-engine-roadmap.md` 含 2026-07-04 历史叙述；文中凡把 Cursor 写成受治理 executor 或 `loop` 的 `cursor-fix` 动作，均为**历史叙述**，现状以 Pi-only + 显式 `cursor-prompt` sidecar 为准。
+
+## 已收敛为 archive / 历史基线（非未来）
+
+- 第 1–2 月规划已收敛为 archive/reports 指针，不在本文展开：`docs/design/archive/2026-07-12-第二月规划.md`。
+- `docs/reports/2026-07-02-repository-analysis.md` 自 2026-07-14 起冻结为**历史基线快照**（允许有限再采样），不当第二 CHANGELOG。
+- 活能力短摘要在 `docs/reports/current-capability-summary.md`。
+- 专题证据按类型落在 `docs/reports/{feature,init-evolution,merge,fullstack-dogfood,dogfood}/`。
+
+## 文档本体的演进边界
+
+- 本目录新增文档随发布包发布（`package.json` `files` + manifest `packageRequired` 显式条目），但 **不**投影到目标项目 init surface；目标项目 init 仍只投影语言无关的 `runtime-boundaries.md`。
+- `runtime-boundaries.md` 是边界真源；本目录其他文档交叉引用，不复制其 import 方向表 / governance-hook 表 / 版本化自举边界表。
+- 未来如有能力落地，应先改 `src/` / CLI / ADR / completed plan，再回写本目录的「已实现」表与站上 `website/docs/overview/*` 短索引。

package/docs/architecture/system-overview.md

@@ -1,100 +1,100 @@
-# 系统全景
-
-本页用一张全景图说明 loop-agent、agent-worker、治理层与外部系统的关系。依赖方向、import 边界与 governance hook 是契约级事实，权威源是 `runtime-boundaries.md`（本页只交叉引用，不复制）。
-
-## 两个 CLI 二进制
-
-发布包 `@tea-agent/loop-agent` 提供两个入口（见 `package.json` `bin`）：
-
-| 二进制 | 入口 | 角色 |
-| --- | --- | --- |
-| `loop-agent` | `bin/loop-agent.js` → `src/cli.ts` | 仓库级 AI coding 任务运行时与治理控制器 |
-| `agent-worker` | `bin/agent-worker.js` → `src/worker/cli.ts` | 产品线 TaskSpec / Feature / Task Pool / Observe 外层适配 |
-
-两个二进制是独立进程，不共享 in-process runtime。`agent-worker` 真正执行 DAG 时通过已发布的 `loop-agent` 子进程调用（详见 `worker-and-feature.md`）。
-
-## 分层概览（交叉引用）
-
-完整分层图、各层职责、允许/禁止的 import 方向见 `runtime-boundaries.md` §分层概览 与 §各层职责。一句话摘要：
-
-```text
-Skill layer      .agents/skills/loop-agent、.agents/skills/agent-worker（Markdown，非 TS import）
-CLI layer        src/cli/ — argv 解析、调用 application/handler、格式化输出
-Application      src/application/ — typed use-case（validate/run/generate DAG 等）
-Workflow runtime src/workflows/ — DAG / Dynamic / Loop 核心执行规则
-Executors        src/executors/ — Pi / shell / static 受治理外部工具适配
-Sidecars         src/sidecars/cursor-prompt — 显式手工 one-shot；不得被 workflow 自动依赖
-Worker adapter   src/worker/ — 产品线适配 + Observe；子进程调用已发布 loop-agent
-Infrastructure   src/infrastructure/ — .harness 副作用、run lifecycle、原子写入
-Governance       scripts/check-*.sh、src/governance/ — 防漂移机器校验
-```
-
-## 两条入口路径
-
-### 直接任务路径
-
-```text
-人类 / 主 agent
-  │  写任务源与执行约束（.harness/tasks/<taskId>/source）
-  ▼
-loop-agent（runtime + 治理控制器）
-  │  dag run-task / validate / run-dag / report / doctor / reconcile-run
-  ▼
-workflow runtime（调度 Pi / shell / static 节点）
-  │  证据落入 .harness/dag-runs/{active,paused,completed}/<runId>/
-  └─ report / doctor / promote / closeout 读取并投影证据
-```
-
-### 产品线 Feature 路径
-
-```text
-人类 / 外部调度器
-  → agent-worker（TaskSpec / Feature / Task Pool）
-  → 冻结 controller identity
-  → spawn 已发布 loop-agent 子进程
-  → 同一 DAG runtime 与 executor registry
-  → DAG facts + Task Pool records
-  → Feature review / morning report / Observe（派生只读视图）
-```
-
-`agent-worker` 位于核心 runtime 的**上游调用侧**，不是 DAG 执行完成后的必经下游。Observe 可以在任一路径后读取现有事实，但不会改变执行结果。
-
-### 本地 Operator Console（Official，0.17.x MVP，与 Observe 协作）
-
-- `agent-worker console|doctor` 提供 loopback Operator Console（默认 `127.0.0.1:8790`；本地图形环境 listen 后默认打开浏览器，`--no-open` 禁止）；Happy Path / Interview 策略面、Task Contract 落地与 recovery CTA 已随 **0.17.0–0.17.2** 发布。
-- canonical mutation 只经 sibling 已发布 `loop-agent`（`LoopAgentClient`），不 in-process 跑 DAG kernel。
-- Observe 保持**独立**只读进程（默认 `8787`）；Console 通过 versioned Observe `/api/health`（`schemaVersion`、`repoFingerprint`、route capabilities）做深链 fail-closed，**不** mount / proxy。
-- openCode 等主会话仍是 Compatibility / Operator Assist，与 Official Console **不等同**。设计锚点：ADR 0005、`docs/design/archive/2026-07-21-local-operator-console-from-pi-web.md`；handoff `docs/reports/feature/2026-07-22-console-mvp-handoff.md`。
-
-## 外部边界
-
-- npm 发布包：`@tea-agent/loop-agent`，包含两个 bin 与静态能力资料。
-- 目标仓库：`loop-agent init` 投影语言无关治理资料；源码仓库专用架构文档只随包可读，不默认投影。
-- 本地文件系统：`.harness/` 保存运行态事实；Git 工作树保存代码、治理文档与长期交接资料。
-- 远程 Git/PR/CI、云 Worker 与云 Task Pool 当前不是核心 runtime 的已实现内置边界，见 `evolution.md`。
-
-## 治理层入口
-
-治理检查是机器校验，不是文档约定。主入口：
-
-- `scripts/check-repo.sh` — 聚合入口，CI / in-flight DAG 均调它。
-- 子脚本：`scripts/check-architecture-boundaries.sh`（import 边界）、`scripts/check-command-registry-drift.sh`（command registry）、`scripts/check-skill-entry.sh`（公共 skill entry）、`scripts/check-doc-index.sh` / `scripts/check-doc-links.sh`（文档链接）、`scripts/check-init-surface.sh`（package/init surface 契约）、`scripts/check-init-evolution-needed.sh`（高影响变更需报告）。
-- `src/governance/**` — 治理逻辑与相关 Vitest。
-- `scripts/self-host-canary.mjs` — 源码仓库的 deterministic candidate takeover 证据入口；**不**属于发布 package surface。
-
-完整的 governance hook 表（哪个脚本检查什么、失败条件）见 `runtime-boundaries.md` §Governance 钩子。
-
-## 受治理 Agent runtime = Pi-only
-
-自 0.10.0 起受治理 Agent runtime 硬切为 Pi-only（ADR 0001）。DAG 中 `dagNodeExecutorSchema = z.enum(["pi","shell","static"])`；`executor: "cursor"` 会抛 `CURSOR_DAG_EXECUTOR_REMOVED_ERROR`。`cursor-prompt` 仅保留为显式手工 one-shot sidecar，不进入 Loop auto-execute 或 Delegate 自动写入。详见 `dag-execution.md` 与 `runtime-boundaries.md` §Executors / §Sidecars。
-
-## 运行态 vs 治理资料 vs 用法文档
-
-| 位置 | 内容 | 权威性质 |
-| --- | --- | --- |
-| `.harness/` | 任务、DAG run、one-shot run、Task Pool、live state | 运行态事实（canonical + derived） |
-| 源仓 `docs/`（目标项目常为 `ai_workspace/loop-agent/`） | 原则、边界、计划、报告、模板 | 治理权威 |
-| `website/docs/` | 使用者/贡献者导读与操作说明 | 用法双树 |
-| `.agents/skills/` | agent 可加载的入口与 reference | 运行时可加载 |
-
-`.harness/` 内部哪些可写、哪些只读、哪些是 derived，详见 `facts-and-state.md`。
+# 系统全景
+
+本页用一张全景图说明 loop-agent、agent-worker、治理层与外部系统的关系。依赖方向、import 边界与 governance hook 是契约级事实，权威源是 `runtime-boundaries.md`（本页只交叉引用，不复制）。
+
+## 两个 CLI 二进制
+
+发布包 `@tea-agent/loop-agent` 提供两个入口（见 `package.json` `bin`）：
+
+| 二进制 | 入口 | 角色 |
+| --- | --- | --- |
+| `loop-agent` | `bin/loop-agent.js` → `src/cli.ts` | 仓库级 AI coding 任务运行时与治理控制器 |
+| `agent-worker` | `bin/agent-worker.js` → `src/worker/cli.ts` | 产品线 TaskSpec / Feature / Task Pool / Observe 外层适配 |
+
+两个二进制是独立进程，不共享 in-process runtime。`agent-worker` 真正执行 DAG 时通过已发布的 `loop-agent` 子进程调用（详见 `worker-and-feature.md`）。
+
+## 分层概览（交叉引用）
+
+完整分层图、各层职责、允许/禁止的 import 方向见 `runtime-boundaries.md` §分层概览 与 §各层职责。一句话摘要：
+
+```text
+Skill layer      .agents/skills/loop-agent、.agents/skills/agent-worker（Markdown，非 TS import）
+CLI layer        src/cli/ — argv 解析、调用 application/handler、格式化输出
+Application      src/application/ — typed use-case（validate/run/generate DAG 等）
+Workflow runtime src/workflows/ — DAG / Dynamic / Loop 核心执行规则
+Executors        src/executors/ — Pi / shell / static 受治理外部工具适配
+Sidecars         src/sidecars/cursor-prompt — 显式手工 one-shot；不得被 workflow 自动依赖
+Worker adapter   src/worker/ — 产品线适配 + Observe；子进程调用已发布 loop-agent
+Infrastructure   src/infrastructure/ — .harness 副作用、run lifecycle、原子写入
+Governance       scripts/check-*.sh、src/governance/ — 防漂移机器校验
+```
+
+## 两条入口路径
+
+### 直接任务路径
+
+```text
+人类 / 主 agent
+  │  写任务源与执行约束（.harness/tasks/<taskId>/source）
+  ▼
+loop-agent（runtime + 治理控制器）
+  │  dag run-task / validate / run-dag / report / doctor / reconcile-run
+  ▼
+workflow runtime（调度 Pi / shell / static 节点）
+  │  证据落入 .harness/dag-runs/{active,paused,completed}/<runId>/
+  └─ report / doctor / promote / closeout 读取并投影证据
+```
+
+### 产品线 Feature 路径
+
+```text
+人类 / 外部调度器
+  → agent-worker（TaskSpec / Feature / Task Pool）
+  → 冻结 controller identity
+  → spawn 已发布 loop-agent 子进程
+  → 同一 DAG runtime 与 executor registry
+  → DAG facts + Task Pool records
+  → Feature review / morning report / Observe（派生只读视图）
+```
+
+`agent-worker` 位于核心 runtime 的**上游调用侧**，不是 DAG 执行完成后的必经下游。Observe 可以在任一路径后读取现有事实，但不会改变执行结果。
+
+### 本地 Operator Console（Official，0.17.x MVP，与 Observe 协作）
+
+- `agent-worker console|doctor` 提供 loopback Operator Console（默认 `127.0.0.1:8790`；本地图形环境 listen 后默认打开浏览器，`--no-open` 禁止）；Happy Path / Interview 策略面、Task Contract 落地与 recovery CTA 已随 **0.17.0–0.17.2** 发布。
+- canonical mutation 只经 sibling 已发布 `loop-agent`（`LoopAgentClient`），不 in-process 跑 DAG kernel。
+- Observe 保持**独立**只读进程（默认 `8787`）；Console 通过 versioned Observe `/api/health`（`schemaVersion`、`repoFingerprint`、route capabilities）做深链 fail-closed，**不** mount / proxy。
+- openCode 等主会话仍是 Compatibility / Operator Assist，与 Official Console **不等同**。设计锚点：ADR 0005、`docs/design/archive/2026-07-21-local-operator-console-from-pi-web.md`；handoff `docs/reports/feature/2026-07-22-console-mvp-handoff.md`。
+
+## 外部边界
+
+- npm 发布包：`@tea-agent/loop-agent`，包含两个 bin 与静态能力资料。
+- 目标仓库：`loop-agent init` 投影语言无关治理资料；源码仓库专用架构文档只随包可读，不默认投影。
+- 本地文件系统：`.harness/` 保存运行态事实；Git 工作树保存代码、治理文档与长期交接资料。
+- 远程 Git/PR/CI、云 Worker 与云 Task Pool 当前不是核心 runtime 的已实现内置边界，见 `evolution.md`。
+
+## 治理层入口
+
+治理检查是机器校验，不是文档约定。主入口：
+
+- `scripts/check-repo.sh` — 聚合入口，CI / in-flight DAG 均调它。
+- 子脚本：`scripts/check-architecture-boundaries.sh`（import 边界）、`scripts/check-command-registry-drift.sh`（command registry）、`scripts/check-skill-entry.sh`（公共 skill entry）、`scripts/check-doc-index.sh` / `scripts/check-doc-links.sh`（文档链接）、`scripts/check-init-surface.sh`（package/init surface 契约）、`scripts/check-init-evolution-needed.sh`（高影响变更需报告）。
+- `src/governance/**` — 治理逻辑与相关 Vitest。
+- `scripts/self-host-canary.mjs` — 源码仓库的 deterministic candidate takeover 证据入口；**不**属于发布 package surface。
+
+完整的 governance hook 表（哪个脚本检查什么、失败条件）见 `runtime-boundaries.md` §Governance 钩子。
+
+## 受治理 Agent runtime = Pi-only
+
+自 0.10.0 起受治理 Agent runtime 硬切为 Pi-only（ADR 0001）。DAG 中 `dagNodeExecutorSchema = z.enum(["pi","shell","static"])`；`executor: "cursor"` 会抛 `CURSOR_DAG_EXECUTOR_REMOVED_ERROR`。`cursor-prompt` 仅保留为显式手工 one-shot sidecar，不进入 Loop auto-execute 或 Delegate 自动写入。详见 `dag-execution.md` 与 `runtime-boundaries.md` §Executors / §Sidecars。
+
+## 运行态 vs 治理资料 vs 用法文档
+
+| 位置 | 内容 | 权威性质 |
+| --- | --- | --- |
+| `.harness/` | 任务、DAG run、one-shot run、Task Pool、live state | 运行态事实（canonical + derived） |
+| 源仓 `docs/`（目标项目常为 `ai_workspace/loop-agent/`） | 原则、边界、计划、报告、模板 | 治理权威 |
+| `website/docs/` | 使用者/贡献者导读与操作说明 | 用法双树 |
+| `.agents/skills/` | agent 可加载的入口与 reference | 运行时可加载 |
+
+`.harness/` 内部哪些可写、哪些只读、哪些是 derived，详见 `facts-and-state.md`。