ECC 2.0 参考架构¶

当前执行镜像： ECC-2.0-GA-ROADMAP.md。

本文档将 2026 年 5 月的参考扫描转化为具体的 ECC 待办事项形态。它不是第二份战略备忘录：以下每一项参考压力都应落地为适配器、检查项、可观测信号、安全策略、PR 评审接口或发布就绪门禁。

参考基线¶

快照日期：2026-05-12。

架构形态¶

ECC 2.0 应是一个框架操作系统，而不仅仅是命令、智能体和技能的清单。

┌──────────────────────────────────────────────────────────────┐
│ Operator Surface                                             │
│ CLI, plugin, TUI, HUD/statusline, release gates, PR checks   │
├──────────────────────────────────────────────────────────────┤
│ Harness Adapter Layer                                        │
│ Claude Code, Codex, OpenCode, Cursor, Gemini, Zed, dmux,     │
│ Orca, Superset, Ghast, terminal-only                         │
├──────────────────────────────────────────────────────────────┤
│ Worktree, Session, And Queue Runtime                         │
│ worktrees, panes, sessions, todos, checks, merge/conflict    │
│ queues, notification state, ownership, handoff exports       │
├──────────────────────────────────────────────────────────────┤
│ Observability And Evaluation Loop                            │
│ JSONL traces, status snapshots, risk ledger, harness audit,  │
│ scenario specs, verifiers, promoted playbooks, RAG sets      │
├──────────────────────────────────────────────────────────────┤
│ Security And Commercial Platform                             │
│ AgentShield policies/SARIF, ECC Tools checks, billing,       │
│ Linear/GitHub sync, enterprise reports                       │
└──────────────────────────────────────────────────────────────┘

参考到待办事项映射¶

工作树与会话编排¶

从 Orca、Superset、dmux 和 Ghast 中采用：

• 工作树生命周期事件：创建、恢复、暂停、停止、差异、评审、PR、可合并、冲突、过期、关闭、抢救。
• 按仓库、分支、cwd、任务、所有者和框架进行会话分组。
• 用于发布通道、PR 分诊通道、文档通道、安全通道和测试编写通道的预设工作区。
• 针对被阻塞的 CI、脏工作树、合并冲突、过期评审和已完成的自主运行的通知。
• 能够标注差异和 PR 的评审循环，同时不将所有权从维护者手中夺走。

仓库工作：

• everything-claude-code：扩展适配器合规矩阵和公开记分卡入门路径。
• ecc2：在添加托管遥测之前，通过稳定的本地负载暴露会话/工作树状态。
• ECC-Tools：消费相同的生命周期事件，用于 PR 检查、问题路由和 Linear 同步。

验证：

• npm run harness:audit -- --format json
• npm run observability:ready
• 当矩阵从文档迁移到数据后，执行有针对性的适配器矩阵测试

HUD、状态与可观测性¶

从 Claude HUD 和 Claude Code 源码审查中采纳：

• 上下文压力：用量、压缩风险、大结果警告以及摘要状态。
• 工具活动：当前工具、最近工具、持续时间、风险操作以及权限请求。
• 代理活动：活动子代理、委派任务、分支/工作树以及等待状态。
• 队列活动：未关闭的 PR/issue、CI 状态、陈旧/冲突批次、评审状态以及已关闭陈旧项的回收积压。
• 成本/风险：Token 成本估算、破坏性操作风险、hook/MCP 风险以及安全扫描状态。

仓库工作：

• 将 docs/architecture/observability-readiness.md 保留为面向操作人员的就绪门禁。
• 定义一个版本化的 HUD/状态 JSON 契约，使 ECC2 和 ECC Tools 都能消费它。
• 在构建可视化 UI 之前，将来自 loop-status、session-inspect、harness 审计和风险台账的示例导出添加到 fixture 目录中。

验证：

• npm run observability:ready
• 对每个状态 payload 进行 fixture 校验
• 对读取会话历史的命令进行跨平台冒烟测试

自改进 Harness 循环¶

从 Meta-Harness、Autocontext 和 Hermes Agent 中采纳：

• 将循环拆分为观察、提案、验证、晋升和回滚。
• 将每项拟议改进存储为 trace 加 artifact，而不仅仅是最终变更文件。
• 只有在验证器证明它们能改进某个场景且不扩大爆炸半径后，才晋升 playbook。
• 使用 RAG/参考集来覆盖经过审核的 ECC 模式、团队历史、CI 失败、评审结果、harness 配置质量以及安全决策。

仓库工作：

• everything-claude-code：记录场景规范、验证器契约以及 playbook 晋升规则。
• ECC-Tools：将分析器发现映射到 PR 评论、check run 和 Linear 任务，同时避免淹没工作区。
• agentshield：将 Prompt-injection 和配置风险发现输入回归测试套件。

当前原型：

• docs/architecture/evaluator-rag-prototype.md 定义了只读 evaluator/RAG artifact 契约。
• examples/evaluator-rag-prototype/ 记录了陈旧 PR 回收的第一个场景规范、trace、报告、候选 playbook 和验证器结果。

验证：

• 只读原型，输出 trace、报告、候选 playbook 和验证器结果
• 证明不良提案被拒绝的回归 fixture

AgentShield 企业安全平台¶

AgentShield 应从实用扫描器演进为企业安全平台。

待办事项形态：

• 用于组织基线、规则严重级别、负责人、例外、过期时间、证据和审计跟踪的策略 schema。
• 用于 GitHub 代码扫描的 SARIF 输出。
• 用于 OSS、团队、企业、受监管、高风险 hooks/MCP 以及 CI 强制执行的策略包。
• 用于 MCP 包、npm/pip 来源、CVE、typosquat 和依赖信誉的供应链情报。
• Prompt-injection 语料库和回归基准。
• JSON 以及高管 HTML/PDF 报告输出。

验证：

• schema 单元测试
• SARIF fixture 测试
• 策略包黄金测试
• 来自公开 issue 历史的误报回归测试

ECC Tools 商业与评审平台¶

ECC Tools 应成为用于计费、深度分析、PR 检查和 Linear 进度跟踪的 GitHub 原生层。

待办事项形态：

• 在任何付款公告之前，进行原生 GitHub Marketplace 计费审计：套餐、席位、组织/账户映射、订阅状态、超额行为、降级/取消行为以及故障模式。
• 范围可与 GitGuardian、Dependabot、CodeRabbit 和 Greptile 的有用部分相媲美的深度分析器：安全证据、依赖风险、CI/CD 建议、PR 评审行为、配置质量、Token/成本风险以及 harness 漂移。
• 覆盖经过审核的 ECC 模式、历史 PR 结果、依赖公告、CI 失败、评审决策和团队特定约定的 RAG/参考集。
• 将发现映射到项目状态、里程碑证据和负责人可处理 issue 的 Linear 同步，同时避免耗尽 issue 限额。

验证：

• check-run fixture 测试
• 计费 webhook 重放测试
• 分析器黄金 PR fixture
• Linear 同步演练 fixture

已关闭陈旧项回收通道¶

关闭陈旧 PR 可保持公共队列可用，但不应因为贡献者没有时间 rebase 而丢失有用工作。

执行规则：

1. 以清晰礼貌的评论关闭陈旧、冲突或过时的 PR。
2. 将它们记录到回收台账中，包括源 PR、作者、关闭原因、有用文件/概念、风险以及建议的维护者操作。
3. 在清理批次之后，手动检查每个已关闭 PR 的 diff。
4. 仅当补丁仍可干净应用并保持当前架构时才 cherry-pick。否则，在新的维护者分支中重新实现有用想法。
5. 在 commit 正文或 PR 正文中保留署名。
6. 当有用工作落地时，在源 PR 上回复评论，并链接维护者 PR 或已合并 commit。
7. 将台账项标记为已落地、已被取代、Linear 跟踪或无需操作。

必需保障措施：

• 切勿盲目 cherry-pick 生成的变更、批量本地化或依赖主版本变更。
• 优先使用小型维护者 PR，而不是一个回收巨型分支。
• 运行与常规代码、文档或目录变更相同的验证门禁。
• 即使最终实现被重写，也要保留贡献者署名。

近期实施顺序¶

1. 扩展 harness 适配器矩阵和公共记分卡入门路径。
2. 在 rc.1 发布之前，使用最新的最终 commit 证据保持发布/名称/插件发布清单最新。
3. 定义 HUD/状态 JSON 契约和 fixture 目录。
4. 启动 AgentShield 策略 schema 以及 SARIF fixture。
5. 审计 ECC Tools 计费和 check-run 表面。
6. 将遗留文件夹和已关闭陈旧 PR 清点到回收台账中。
7. 通过小型署名维护者 PR 移植有用的陈旧工作。

非目标¶

• 在本地事件模型有用且可测试之前，提供托管遥测。
• 在没有验证器证据的情况下，自动修改用户运行框架配置。
• 将任何单一智能体运行框架视为标准接口。
• 在命令、软件包、市场和计费证据最新之前，发布或支付公告。