[Plan] Full-repo review of aevatar — 分阶段 + 多模型 + 新通用 module-review skill

[eanzhao]

[Plan] Full-repo review of aevatar — 分阶段 + 多模型 + 新通用 module-review skill

TL;DR

目标：在 2-3 个月内完成对 aevatar 整个 repo（132 csproj / ~387k LOC / 70+ src 项目 + 23 agents + 38 test）的系统化 review，输出可追踪、可归档、可增量更新的 finding 清单。

方法：

1. 把 repo 切成 ~28 个 review 单元（按"权威层 + 业务子系统 + 横切专题"组合切分），每单元一次会话内可消化。
2. 写一个新通用 skill，基于 opencode-pr-review 改造：复用同一组 6 个 reviewer（3 opencode + kimi + gemini + codex），但输入从 PR diff 改为 任何 repo 的模块/目录/专题；可被 schedule 触发。
3. finding 直接 post 为 discussion（无需人工预审），人审确认后再开 issue。github 即跟踪面，不再单独归档到 docs/audit-scorecard/。
4. 启动顺序：从最稳定的底盘（Foundation.Abstractions）开始，逐层向上。

---

1. 现状摘要

指标	值
总 csproj	132（src 70+ / agents 23 / test 38 / tools 2）
总 .cs LOC	~387k
已有 ADR	18 个（0001 ~ 0018）
已有 audit scorecard	3 份（最新 2026-04-27 daily pipeline review）
上次综合健康度	5.5/10（2026-04-08 audit）
已识别 critical 问题	投影管线 6+ 处 bypass / agents 中间层状态 / AI.Core SkillRegistry 锁滥用 / Workflow lease 韧性
待办 refactor issue	#444-#450 系列（daily 流水线）/ #491 / #498 / #500 / #516 / #519 等
最大项目	Workflow.Core 13.6k / GAgentService.Hosting 7.7k / Studio.Application 7.4k / Studio.Hosting 6.7k / AI.Core 6.6k

Audit 盲区（基于现有 scorecard 自述）：

• agents/ 与 apps/ 不在大多数 CI guard 扫描范围
• tools/Aevatar.Tools.Cli 与 tools/Aevatar.Tools.Config 未做过完整架构 review
• Aevatar.Authentication.Providers.NyxId 流缺专项回归保护
• VoicePresence / Interop.A2A / Presentation.AGUI 几乎没有专项 audit
• 测试体系本身的稳定性与隔离边界（轮询 / mock 与 real / 共享 fixture）

---

2. 总体策略

2.1 切分原则

维度	处理
按层	Foundation → CQRS/Projection → 横切（Auth/Bootstrap/Hosting）→ 业务子系统（AI/Workflow/Studio/Scripting/...）→ GAgents → Platform/Tools → 宿主 → 测试
按业务子系统	同层内按业务域聚类，避免单次 review 跨太多无关代码
按规模	单次 review 目标 < 8k LOC + 紧密相关 canon docs；超出则二次切分
按横切专题	单层完成后开横切专题（序列化、投影一致性、Actor 生命周期、DI、secret material、可观测性、文档 drift）

2.2 评审深度档位

档	适用	产出
quick	阅 README + 接口签名 + 主要文件结构	模块定位 / 关键 seam / 是否值得 deep review
standard	全部 .cs + 相关 .proto + 相关 canon	finding 列表（含 severity × category），交叉引用 CLAUDE.md / canon
deep	standard + 调用方追溯 + 测试覆盖 + ADR 一致性	完整模块 audit 报告，含修复建议与 issue 草稿

底盘层（Foundation / CQRS）默认 deep；业务子系统默认 standard；GAgent 默认 quick → 命中风险后升级。

2.3 评审维度（每单元都要查）

继承 opencode-pr-review 的清单（DI / arch / concurrency / bug / security / perf / test），加上 aevatar 专属：

• CLAUDE.md 顶级约束：分层、统一投影链路、Actor 即业务实体、读写分离、Metadata 决策树、Protobuf 强制、命名语义优先
• canon doc 一致性：实现是否仍与 docs/canon/<topic>.md 描述一致；canon drift 也是 finding
• ADR 兑现度：相关 ADR 是否落地（特别是 0014 / 0015 / 0017 / 0018）
• 删除测试（deletion test）：哪些抽象 / pass-through 中间层可以直接删
• Depth vs Shallow：接口对调用方的 leverage 是否真的存在
• One adapter = hypothetical seam：单 adapter 的 Port 是否构成"未来可能要换"的过度抽象

---

3. Review 单元清单（执行顺序）

总计 28 个单元 + 8 个横切专题，估算 30-50 次会话。括号内为优先级（P0 阻塞 / P1 高 / P2 中 / P3 低）和深度。

阶段 0：Bootstrap（1 单元）

• U00 · skill 自身验证（P0 / quick）—— 写完新 skill 后选 1-2 个小模块（如 Aevatar.Configuration、Aevatar.Interop.A2A.Abstractions）做 dry-run 验证

阶段 1：底盘（5 单元 / deep）—— 从这里开始

• U01 · Foundation.Abstractions（P0 / deep）—— 契约层；所有上层都依赖它的语义稳定性
• U02 · Foundation.Core（P0 / deep）—— GAgentBase / Pipeline / Hook / RunManager / StateGuard
• U03 · Foundation.Runtime + Implementations.Local（P0 / deep）—— 本地 actor 模型，是测试基线
• U04 · Foundation.Runtime.Implementations.Orleans + Streaming + Kafka + Garnet（P1 / deep）—— 生产运行时
• U05 · CQRS.Core / Projection.Core / Projection.Runtime / Stores.Abstractions（P0 / deep）—— 读写分离骨架；上次 audit 评分 4-5/10，重点

阶段 2：横切支撑（4 单元）

• U06 · CQRS.Projection.Providers.{Elasticsearch, Neo4j, InMemory}（P1 / standard）—— 与 Standardize Elasticsearch projection index mappings for stable read model fields #533（ES index mapping 标准化）联动
• U07 · Authentication.{Abstractions, Hosting, Providers.NyxId}（P1 / deep）—— 上次 audit 标识为缺专项保护
• U08 · Configuration（P2 / standard）—— 一个 csproj 但配置全局
• U09 · Bootstrap + Bootstrap.Extensions.AI + Hosting（P1 / standard）—— DI 装配的最后防线

阶段 3：业务子系统（8 单元）

• U10 · AI.Abstractions + AI.Core（P0 / deep）—— 6.6k LOC；上次 audit 4/10，SkillRegistry / StreamingToolExecutor 重点
• U11 · AI.LLMProviders.{MEAI, NyxId, Tornado} + AI.Infrastructure.Local（P1 / standard）
• U12 · AI.ToolProviders（连接外部能力的）：MCP / NyxId / Lark / Telegram / Web / Skills / ServiceInvoke / ChannelAdmin / Channel / Scripting / Workflow / AgentCatalog / Binding / ChronoStorage / Ornn（P1 / standard，按子族切两次）
• U13 · Workflow.Abstractions + Workflow.Core + Workflow.Application（含 Abstractions）（P0 / deep）—— 13.6k LOC 是仓里最大单项目；core engine
• U14 · Workflow.Infrastructure + Workflow.Projection + Workflow.Sdk + Workflow.Presentation.AGUIAdapter + workflow/extensions（P1 / standard）
• U15 · Scripting.{Abstractions, Application, Core, Hosting, Infrastructure, Projection}（P1 / standard）
• U16 · Studio.{Application, Domain, Hosting, Infrastructure, Projection}（P1 / deep，因为 4 个 5k+ 项目都在这里）
• U17 · Interop.A2A + VoicePresence + Foundation.ExternalLinks.WebSocket + Presentation.AGUI（P2 / standard）

阶段 4：GAgents（4 单元，按业务域）

• U18 · Channel 系列：Channel.Abstractions / Channel.Identity / Identity.Abstractions / Channel.Runtime / channels/（含 NyxIdRelay、Lark、Telegram）（P0 / deep）—— 上次 audit 多处 bypass 都在这里
• U19 · Streaming 系列 + 流水线 GAgent：StreamingProxy / StreamingProxyParticipant / Scheduled / NyxidChat / ChatHistory / ChatbotClassifier（P0 / deep）—— 包含 refactor(skill-runner): split SkillRunnerGAgent into SkillDefinitionGAgent + SkillExecutionGAgent #491 拆分 / NyxIdChatEndpoints 三处 bypass
• U20 · 用户/产品域 GAgent：UserConfig / UserMemory / Household / Device / RoleCatalog / ConnectorCatalog / Registry / StudioMember / StudioTeam / Authoring.Lark（P1 / standard）
• U21 · agents/platforms + agents/channels（P1 / standard）

阶段 5：Platform & Tools（3 单元）

• U22 · platform/Aevatar.GAgentService. (含 Governance.* 全套)*（P0 / deep）—— 7.7k LOC GAgentService.Hosting 是 Endpoint God Class 重灾区
• U23 · tools/Aevatar.Tools.Cli + Aevatar.Tools.Config + tools/connectors / cluster / observability / symphony（P2 / standard）
• U24 · apps/aevatar-console-web（P2 / standard）—— 前端，按 frontend-design canon 评

阶段 6：宿主（2 单元）

• U25 · Aevatar.Mainnet.Host.Api（P0 / deep）—— 生产入口；与 bug(mainnet): NyxIdSpecCatalog 持续 401 — SpecFetchToken 未在 MainnetHostBuilderExtensions 中绑定，生产 catalog 一直为空 #522（NyxIdSpecCatalog）联动
• U26 · Aevatar.Workflow.Host.Api（P1 / standard）

阶段 7：测试体系（1 单元，可拆）

• U27 · 测试架构 review（P1 / standard）—— 38 个测试项目，重点：(a) 隔离边界（unit/integration/slow）；(b) 轮询/Mock/共享 fixture；(c) Architecture.Tests 与 CI guard 的覆盖盲区

阶段 8：横切专题（5+ 单元，按需开）

• T01 · 序列化合规：全仓 Protobuf vs JSON 边界审查（CLAUDE.md "禁止 JSON / XML / 自定义字符串格式"）
• T02 · 投影管线一致性：基于 audit 04-08 的 P1-P6 + 重新扫描；产出 follow-up issue
• T03 · Actor 生命周期 + 中间层进程内状态：扫所有 ConcurrentDictionary / Dictionary<> / 静态注册表
• T04 · DI / 注册一致性：跨 csproj 验证生命周期匹配
• T05 · Secret material 流：NyxID API key / 凭据 / token；与 harden(webhook): nyxid-relay handler must accept-fast and persist to inbox before processing #449 / refactor(daily-credential): introduce AgentExecutionCredentialGAgent — proxy API key as actor-owned resource #445 / refactor(daily-catalog): make UserAgentCatalogGAgent pure set-membership; projector consumes SkillRunner committed events directly #444 / Harden HMAC-key-at-rest boundary for AevatarOAuthClient projection store #526 联动
• T06 · 错误模型 / 重试 / 死信：与 bug(foundation): RuntimeEnvelopeRetryPolicy disabled by default conflicts with projection scope handler 'drop pending and re-execute' contract #529 / bug(channel-runtime): LLM reply inbox stream DeliverBatch 30s timeout causes duplicate ProcessAsync (double LLM call & billing) #528 / bug(daily): SkillRunner masks GitHub tool failures as silent "no activity" successful runs #439 联动
• T07 · Observability：trace / log / metric 是否覆盖 critical path
• T08 · 文档与代码 drift：canon vs 实现；ADR 兑现度

---

4. 新通用 skill：opencode-module-review（暂名）

4.1 设计原则

基于 opencode-pr-review 改造，复用同一组 6 个 reviewer，做成通用工具——不绑死 aevatar，可被 schedule 触发，对任何 repo 的任意模块/专题做 review。

4.2 与 opencode-pr-review 的差异

维度	pr-review	module-review
输入	<pr-number>	<scope>：目录 / .csproj / .slnf / glob / 专题主题
repo 绑定	当前 worktree	任何 repo（支持 --repo owner/name --ref <sha|branch>）
触发方式	手动 / /opencode-pr-review	手动 + /schedule（cron）
范围数据来源	gh pr diff	文件清单 + 摘要 + 自动注入的 canon docs（如有）
上下文打包	diff 自包含进 prompt	scope 太大无法全塞；改用 "manifest + reviewer 自取读"
评审颗粒	行级 inline comment	模块级 finding（带 path:range）
共识 cluster key	(path, side, line) ±2	(theme, scope, finding-class) 模糊匹配
输出位置	PR inline comment	GitHub Discussion（默认，无需人工预审） + 人审后转 issue
增量	每次都全量	支持 --baseline 跳过已结案的 finding

4.3 参数

opencode-module-review <scope>
  [--repo owner/name]              # 默认当前 worktree
  [--ref <sha|branch|tag>]         # 默认 HEAD
  [--canon <doc1,doc2,...>]        # 强制 reviewer 阅读哪些 canon doc 作为基准
  [--depth quick|standard|deep]    # 默认 standard
  [--theme <topic>]                # 横切专题：projection / serialization / di / actor-lifecycle / secrets / observability / docs-drift
  [--reviewers <csv>]              # 同 pr-review，默认同一组 6 个
  [--discussion-category <name>]   # 默认 General；finding 直接 post 到此 category
  [--baseline <previous-report.json>]
  [--dry-run]

4.4 Procedure 概要

1. Resolve scope
   • 目录 / .csproj / .slnf → 列文件
   • glob → 展开
   • --theme → 用预定义 grep 模式找入口（如 serialization → JsonSerializer | System.Text.Json）
   • 跨 repo：gh repo clone 到 /tmp/.../<repo>-<ref>/ 或用 worktree
2. 建 manifest：每个文件 path + LOC + 主要 symbol
3. 自动选择 canon（若 repo 有 docs/canon/）：根据 scope 命中关键字注入
4. 写 prompt（与 pr-review 共享框架；替换 --- diff --- 为 --- file manifest --- + --- relevant canon --- + 提示 reviewer 用 file-reading 工具自取）
5. 并行启动 reviewer（同 pr-review：3 opencode + kimi + gemini + codex）
6. 解析 + cluster（key 改为 theme+scope）
7. 直接 post discussion（默认无人工预审）：
   • 主帖 = scope 概况 + finding 摘要表
   • 每条共识 finding 一条 reply（含 severity / category / models / 引用 path:range）
   • 单模型意见折叠在主帖底部
8. 后续：用户在 discussion 上 confirm → 该 finding 转为 issue（带 audit-finding + audit/<unit-id> + severity/<sev> label）

4.5 与 pr-review 共享的部分

• reviewer launcher（opencode/kimi/gemini/codex 子进程封装）
• ANSI 剥离 + JSON 抽取
• consensus 聚合（key 替换即可）
• 输出展示模板

实施建议：先复制 opencode-pr-review SKILL.md 改造，跑通 2 个单元后，把通用部分抽到 opencode-review-shared helper。先验证模式，再抽象。

4.6 Schedule 用法示例

# 每周一对 aevatar 的 Foundation 层做 standard review
/schedule "0 9 * * 1" /opencode-module-review src/Aevatar.Foundation.Core --repo aevatarAI/aevatar

# 横切专题：每月扫一次序列化合规
/schedule "0 9 1 * *" /opencode-module-review --theme serialization --repo aevatarAI/aevatar

# 跨 repo：一次性对 NyxID 做 deep review
/opencode-module-review src --repo ChronoAIProject/NyxID --depth deep

---

5. 跟踪机制

物件	用途
本 Discussion	全局规划主帖 + 阶段 checkpoint
每单元一个 child Discussion	review 报告 + finding 共识列表（自动 post）
audit-finding label	标记由 review 转化的 issue
audit/<unit-id> label	标记属于哪个 review 单元（U01-U27 / T01-T08）
severity/{blocker,major,minor,nit} label	同 reviewer schema

不再单独归档到 docs/audit-scorecard/——github discussion + issue 就是跟踪面。

---

6. 节奏与下一步

节奏：每周推进 2-3 个单元；每完成一阶段（5-7 个单元）做一次综合健康度更新；遇到 P0 finding 立刻拆 issue 不等阶段结束。

已确定方向：

• ✅ 切分方案：U00-U27 + T01-T08
• ✅ 新通用 skill：基于 opencode-pr-review 改造，跨 repo + 可 schedule
• ✅ 输出：finding 直接 post 到 Discussion（无需人工预审），人审 confirm 后转 issue；不归档到 docs/audit-scorecard/
• ✅ 启动顺序：从最稳定的 U01 (Foundation.Abstractions) 开始

下一步：

1. 把 opencode-module-review skill 写出来
2. 跑 U00（小模块 dry-run 验证）
3. 进入 U01 (Foundation.Abstractions)

cc 维护者们；欢迎对单元划分 / 横切专题做补充。