@tea-agent/loop-agent 0.37.0 → 0.37.1-beta.0

package/docs/architecture/evolution.md

@@ -1,108 +1,73 @@
-# 架构演进：当前内核与未来边界
+# 架构演进：当前 vs 未来
 
-本文区分 `loop-agent` 当前已实现架构和第 3–6 月前瞻。当前事实以代码、`CHANGELOG.md`、`docs/reports/current-capability-summary.md` 与 completed/active plans 为准；路线以 `docs/design/active/六个月规划.md` 为准。
+本页区分 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.35.3`（2026-08-16）。
+**对照版本：`@tea-agent/loop-agent@0.24.0`（2026-07-27）**。细节版本条目见根 `CHANGELOG.md`；本表只保留架构层可读摘要。
 
-## 当前架构
+## 当前已实现（累计至 0.24.0）
 
-```text
-Skills / AGENTS
-      ↓
-loop-agent CLI → application use cases → workflow runtime → Pi/Shell/Static executors
-      ↓                                  ↓
-task source / contracts              run-owned facts / artifacts / receipts
-
-agent-worker CLI / Console
-      ↓ frozen published controller subprocess
-loop-agent CLI
-```
-
-### 已实现能力
-
-| 域 | 当前事实 | 权威入口 |
+| 域 | 现状 | 权威入口 |
 | --- | --- | --- |
-| 标准生命周期 | `task advance` 是唯一标准 mutation 入口；`task status` 只读；run 级 `dag` 命令保留为 advanced recovery/forensic | ADR 0008、`docs/governance/feature-workflow.md` |
-| DAG kernel | Contract/Scout/Plan/Implement/Verify/Closeout；dynamic workflow、pause/resume、doctor/report/rerun/reconcile | `dag-execution.md`、`agent-dag-runner.md` |
-| 写入与契约 | Pi-only writer、Task Contract、DagSpec v4 binding、writeSet review、writer admission、write guard | ADR 0001、`runtime-boundaries.md` |
-| 专用 taskKind | `frontend-implementation`、`backend-test`、`frontend-test`、knowledge 路径；显式 taskKind 贯穿 intake→task→DAG | `CHANGELOG.md [0.35.0]`–`[0.35.3]` |
-| Backend test | map-shard、execution readiness、generated-output conflict、collection/pytest 结构化失败、恢复加固 | completed plans、`CHANGELOG.md [0.30.0]`–`[0.31.1]` |
-| Frontend implementation | canonical prewrite result、两层 writer gate、统一 writer helper、rollback journal、child recovery、root manifest | completed `2026-08-13-frontend-implementation-dag-optimization.md` |
-| Frontend test | lean 默认 DAG、case map、evidence/quality report；安全边界 hard gate，内容质量 advisory | completed `2026-08-07-frontend-test-dag-lean-nodes.md` |
-| Worker / Feature | TaskSpec、feature-scoped Task Pool、Ready Planner、Outcome、Verification Bundle、Delivery/Closeout | `worker-and-feature.md`、current capability summary |
-| Worker readiness baseline | Attempt identity、immutable owner、lineage/revision、task-scoped lease、controller protocol、acceptance、reconcile | Agent Worker PR v1 Phase 1–7 / `0.32.0` |
-| Operator Surface | 裸 `agent-worker console`；Operate、`/inspect/`、Operator Chat、recovery CTA、intake bridge | ADR 0005、0011–0013 |
-| 自举与验证 | controller identity、skill snapshot、deterministic/live canary、verified tarball、`verify:tree` receipt | `runtime-boundaries.md`、verification matrix |
-
-### 当前不变量
-
-- `loop-agent` 拥有 repo-local DAG kernel；`agent-worker` 通过冻结的已发布 CLI 子进程执行，不复制内核。
-- 受治理 Agent writer 只有 Pi；`cursor-prompt` 只是显式 one-shot sidecar。
-- shell verification / Final Verification 是完成权威；模型 verdict 与 UI projection 不是。
-- Console 是本地 loopback 控制面；canonical mutation 仍经 sibling CLI/application contract。
-- controller identity 和 run-owned skill snapshot 分属不同冻结层，不能互相替代。
-- recovery 必须保留原始终态并生成显式 reconciliation/continuation 事实。
-
-完整 import 与 runtime 依赖规则见 `runtime-boundaries.md`，本文不复制其机器校验表。
-
-## 当前尚未 Ready
-
-| 项目 | 状态 |
-| --- | --- |
-| Agent Worker PR v1 Phase 8 | `NOT_READY`：burn-in、live Closeout、C4/C7 crash 未收口；live Pi canary 已验证 |
-| Fullstack release train | I40 Delivery/Closeout live；FC-B orphan recovery failed，overall=partial |
-| Operator Chat primary session | 主体能力已发布；event recovery / dogfood 门槛仍 open |
-| frontend-test | formal V7 smoke 与独立成功率报告 open |
-| backend-test | 真实 provider 五路径 smoke blocked-external |
-
-## 下一阶段目标架构
-
-未来能力不直接塞入当前 runtime，而是增加两个外层边界：
-
-```text
-Organization Control Plane
-  Feature Graph / Queue / Policy / Approval / Remote Adapters
-                     ↓ assignment + lease
-Isolated Execution Plane
-  Workspace Manager / published loop-agent / repo-local agent-worker projection
-                     ↓ immutable refs + receipts
-Evidence & Trust Plane
-  Artifact Manifest / Git & CI Receipts / Audit / Metrics / SLO
-```
-
-### 演进顺序
-
-| 阶段 | 新边界 | 不能破坏的旧边界 |
+| 受治理 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 为**设计输入**）。它们**当前不存在于产品声称的线上形态**，或仅有本地/部分替代：
+
+| 未来方向 | 状态 | 规划来源 |
 | --- | --- | --- |
-| 远程交付 | Git/PR/CI adapter、head-bound receipt、approval | repo-local writer gate 与 verification authority |
-| 隔离 Worker | workspace lease、fencing、credential/network policy、artifact projection | frozen controller 与 DAG run facts |
-| 跨仓库 Feature | repo-qualified TaskRef、contract hash、saga/compensation | 每仓库独立 Task/PR/CI/terminal state |
-| 生产治理 | versioned policy、audit、SLO、semi-auto lane | owner opt-in、可撤销授权、fail-closed |
-
-### 未来合同
-
-- `AssignmentEnvelope`
-- `WorkspaceLease`
-- `ControllerAttestation`
-- `GitMutationReceipt`
-- `CiRunReceipt`
-- `ArtifactManifest`
-- `PolicyDecision`
-- `FeatureCloseout`
-
-这些对象必须先有 schema、fixture、verifier、失败语义和 ADR，再接真实 provider。
-
-## 仍属前瞻、禁止写成已交付
-
-- 自动远程 push / PR / CI / merge。
-- 线上队列、容器 Worker Pool、多租户与跨 region 调度。
-- 组织级凭据代理、策略服务与审计服务。
-- 跨仓库原子交付；目标模型是 saga 与补偿，不是伪全局事务。
-- Eval Lab auto-promote、默认自动 merge、自动发布或 RSI Level 1。
-
-## 文档演进规则
-
-1. 新能力先由代码、测试、live campaign、completed plan 或正式报告证明。
-2. 证明成立后更新 current capability summary 和本页“当前架构”。
-3. 未证明部分只保留在 active design/exec-plan，不能通过修改措辞升级状态。
-4. 使用者短索引同步到 `website/docs/overview/roadmap.md`，避免复制长版本流水账。
+| 远程 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/*` 短索引。