feat: 强化 goal 功能——任务执行图 + 可验证收敛 + 缓存/压缩/并行 + 三框架适配（roadmap 提案）

## 使用场景 / Use case

Goal（`/goal`）是 cindy 面向长时自主任务的入口，但当前的实现是**「一段带裁决的循环文本」**：单会话串行续跑、完成判定依赖模型自评、每轮全价重算输入 token、上下文压缩外包给 SDK。随着任务变长（几十轮 / 跨天 / 多模块），四个命脉问题会依次暴露：

1. **成本**——长任务每轮全价重算输入 token，无 prompt caching 收益（`anthropic-compat-proxy-host` 剥离了 `cache_control`），几十轮后成本线性膨胀；
2. **保真**——上下文压缩由 Claude Code SDK 内部处理（`commands.ts`：SDK 内部已实现 /compact），goal 无法控制锚点与时机，存在关键状态丢失风险；
3. **速度**——单会话串行续跑，任务图无依赖节点被白白串行化；每轮全历史重放，注意力开销随轮次增长；
4. **复杂度**——复杂目标无法递归拆解，一次性文本不可见"干到哪一步"，失败无法局部重试。

此外 goal 目前只针对单一 agent 框架验证，Claude Code / Codex / Pi 三框架的完成判定信号各异（Stop hook / task_complete 事件 / RPC 事件流），无统一抽象，goal 在三框架上的可靠性无保障。

## 当前问题 / Current limitation

- **无任务分解**：objective 是一次性文本，无 checklist / DAG，用户看不到进度、agent 无法局部重试（相关：#1734/#2065 真实进度优先）。
- **完成判定只依赖 LLM 自评**：无外部可验证信号（测试通过 / diff 收敛），业界判定为最弱判据。
- **无缓存工程**：`cache_control` 被代理层剥离，无稳定前缀纪律、无命中率监控。
- **压缩不可控**：外包给 SDK，goal 无法保证"零丢失"（无 pinned 锚点、无归档回读、无压缩验证）。
- **无并行**：单会话串行，无并发信号量、无独立工作区冲突隔离、无结果归约。
- **无三维预算**：只有 token 与轮数，无 wall-time / step 硬顶；护栏设置 UI 未接线（`goal-settings-store` 预留未连）。
- **无 checkpoint 粒度恢复**：只有"重启 resume"，无子任务级 checkpoint / safe-point 中断。
- **三框架未抽象**：verdict 逻辑散落、无 capability 探测，Pi（无 schema 约束）上可靠性未验证。
- **终态收口痛点**：turn / plan / subagent 终态未正确写回（#1868/#2045/#2091/#1822 同源）。

## 期望方案 / Proposed solution

基于两轮业界调研（Anthropic context engineering / LangGraph / Codex CLI / Claude Graph / Reflexion / HTN 规划等），以 **11 个工程维度**重构 goal。核心判断：goal 强化的成败不在 prompt 写得更好，而在 **harness（状态持久化/中断恢复/预算兜底）+ context（pinned 锚点/schema 压缩/缓存前缀纪律）**。

### 架构总览

```
Goal(终点线合约: objective + done-when[] + constraints[] + budgets{})
├─ Graph: GoalWorkUnit DAG + todo —— 递归分解(HTN), 失败局部 replan
├─ Loop: 三层终止(max-steps + 预算硬顶 + 停滞检测) + 收敛判据 test>diff>count>judge
├─ Harness: 三维预算(token/step/wall-time) + 子任务 checkpoint + safe-point 中断
│ + 预算耗尽=WIP+handoff 降级 + 并行执行(信号量 3-8 + 独立工作区)
├─ Context: PINNED 锚点(不可压缩) + Standing State Injection + schema 压缩 + 归档指针化
├─ KV-Cache: 稳定前缀(system+tools+PINNED) + cache_control 断点 + 命中率监控
└─ Multi-Framework: TurnEndSignal 统一事件抽象 + verdict 分级 + capability 探测
```

### 分阶段实施路线（每阶段独立可合并、可回滚；#2104 维护者定调：观测基线前置、试点先行、指标验证不预设承诺）

| 阶段 | 范围 | 风险 |
|---|---|---|
| **P0 观测与验收基线**（最高优先） | Goal run 结构化观测（session/turn generation、状态变化、终态事件、预算消耗、停滞原因、重试/恢复）+ 补齐 6 类测试 | 低 |
| **P1 契约强化** | goal 模板四要素（Goal/Context/Constraints/Done-when）+ 停滞检测 | 低 |
| **P1.5 完成判定分层** | 保留模型裁决兜底 + 新增**可选**外部 verifier（测试/diff/产物校验器），默认不强制 | 低 |
| **P2 最小 work-unit 试点** | 最小 checklist/work-unit + 节点状态 + 局部重试；**先证明 IO 契约/持久化/恢复语义，再决定是否引入递归 HTN/DAG** | 中 |
| **P2.5 缓存前缀工程** | 代理层 cache_control 能力探测（各 provider 真实支持）+ 稳定前缀 + 命中率/TTFT 指标基线，不预设命中率承诺 | 低 |
| **P3 恢复与预算** | 三维预算（wall-time/step 默认值单独评估，不做无兼容强制限制）+ 子任务 checkpoint + safe-point 中断 | 中 |
| **P4 压缩与归档** | PINNED 锚点 + Standing State Injection + schema 压缩 + 归档回读 + 压缩前后状态一致性基线 | 中 |
| **P5 三框架适配** | TurnEndSignal 事件抽象 + adapter 归一 + capability 探测 + verdict 分级 | 中 |
| **P5.1 并行执行** | DAG 拓扑调度 + 并发信号量 + 独立工作区 merge gate + 结构化 report 归约 + 跨框架调度（试点验证后） | 高 |
| **P5.2 并发与协作** | 并行子会话 + 插件 API（#1010）+ 打通 workflow progress | 高 |

### 关键设计决策（11 个工程维度要点）

1. **Graph**：节点=完成条件（非执行路径）+ 可枚举输入 + 结构化输出契约；失败只做局部 replan（≤2 次）；约束逐层下传防意图稀释；真实进度优先（不用推断 completed 覆盖上报状态，#2065/#2072）。
2. **Loop**：三层终止（max-steps + token/step/wall-time 预算硬顶 + 停滞检测，连续 N 轮同反馈转 blocked）；收敛判据 test>diff>count>judge（LLM 自评仅兜底）；终态原子写回防"运行中残留"（#1868/#2045）。
3. **Harness**：三维预算任一超限 → `budgetLimited` + WIP 提交 + handoff note（不 crash 不死循环）；子任务粒度 checkpoint（崩溃恢复/human pause/跨天续跑）；safe-point 中断 + deferred resume（复用 #1827 解法）。
4. **Context**：goal 定义/约束/Done-when PINNED 逐字保留（Anthropic 实证完成率 78% vs 23%）；每轮 Standing State Injection（紧凑 goal snapshot 独立 system 块，防目标漂移）；schema 化压缩（GOAL/DECISIONS/CONSTRAINTS/TODO/NEXT）+ 渐进 nibble（75% 硬触发）。
5. **Prompt**：goal 模板四要素强制（无 Done-when 拒绝建立）；产出物格式契约（可核验审计表）；执行/评估/反思角色分离（Reflexion，失败教训写回 goal 记忆）。
6. **KV-Cache**：稳定前缀纪律（system+tools+PINNED 前置、断点 ≤4 个、≥1024 token、动态内容绝不进前缀）→ 命中率 ~8%→90%+（Claude Code 实证 92%）；命中率 <50% 告警防静默漂移。
7. **Compaction**：状态外置指针化（原文落盘、上下文留指针回读，>20K 工具输出自动外置）；压缩事件日志（约束哈希断言零丢失）；git 为地面真值。
8. **速度**：并行工具（bridge 已支持）+ 缓存命中 TTFT -20-85% + 短上下文 + 模型路由（#1943）；架构级收益（GQA/speculative decoding/KV 量化）依赖服务端。
9. **递归分解**：HTN 式展开（compound→primitive 递归终止 + maxDepth 3）；粒度四问（可执行/可验证/实质进展/可局部修订）；验证闸门 + 失败预算防 token 爆炸。
10. **三框架适配**：TurnEndSignal 统一事件抽象（Codex task_complete 事件 > Claude Stop hook > Pi 结构化回传 > fenced JSON 文本兜底）+ capability 探测 + schema 优先（Claude `--json-schema` / Codex `--output-schema`）。
11. **并行执行**：DAG 拓扑调度 + 并发信号量（3-8，防并行风暴）+ 独立工作区（git worktree + merge-tree 预检冲突，冲突降级串行）+ 结构化 report 归约（1000-2000 token 摘要回传）+ 跨框架按复杂度调度（综合节点旗舰模型、机械 fan-out 便宜后端）。

### 数据模型扩展

`goal_work_units`（任务图）、`goal_checkpoints`（子任务 checkpoint）、`goal_archives`（状态外置归档指针）、`compaction_log`（压缩验证日志）、`goal_runs`（并行执行记录）；`session_goals` 增列 done_when/constraints/wall_time_budget_ms/step_budget/stall_window/lessons/cache_stats。

### UI 变化

GoalPanel（DAG 可视化 + 三维预算仪表 + 停滞警示）、active 语义分离（idle vs running，#1868）、goal 编辑弹窗四要素表单、并行执行视图。

## 已考虑的替代方案 / Alternatives considered

- **纯 prompt 增强**（改系统提示词让 goal 更"自律"）——业界共识为最弱手段：无预算硬顶、无状态持久化，长任务必然漂移；否决。
- **整体一次重构**（一次 PR 全量落地）——改动面过大（涉及 goal-host/代理层/三框架/存储/UI），评审与回滚风险高；否决，改分阶段（P1→P5.2 每阶段独立可回滚，feature flag 控制）。
- **只做并行不做其他**——并行是吞吐提升，但无预算/无压缩/无缓存时并行只是更快地烧钱；作为 P5.2 置于基础能力之后。
- **压缩继续外包 SDK**——goal 无法控制锚点/时机/保真，"零丢失"无保障；改为 goal 自有压缩层（P4）。

---

*说明：本提案为 roadmap 型设计（完整设计文档已备，含三框架适配矩阵、并行冲突策略、缓存前缀规范、验收标准 13 条）。欢迎维护者与社区对阶段优先级与范围给出方向，认领实现或分阶段拆子 issue 均可。*

This is a broad roadmap rather than a single implementation task. Start by breaking out the P0 observation baseline and inspect the mentioned commands.ts, goal-settings-store, and GoalPanel entry points. Done requires a separately scoped phase with explicit tests and acceptance criteria; the proposal does not define one implementation endpoint.

Written by the indexing model from the issue text.