AI Specialist Value Output — PRD 评审与分阶段实施总方案（v2）
For agentic workers: 本文档是 master plan（评审 + Phase 结构 + 各 Phase 方案）。每个 Phase 动工前用 superpowers:writing-plans 产出该 Phase 的 task 级 TDD 实施计划，再用 superpowers:subagent-driven-development 或 superpowers:executing-plans 执行。
Goal: 把 Specialist 的专业身份变成五个运营侧可配置资产（Soul / Skills / KB / Tools / Feedback loop），版本化、审计、eval 门禁，AM 无需工程师即可配置新 Specialist。
Architecture（v2 核心修订）: 不按资产类型切 Phase，而按"先统一数据模型与存储 → 再统一管理（admin 系统）→ 再统一装配 → 最后拓展"的层次推进。五种资产共享一个配置资产底座（统一的版本 / 审计 / 作用域 / 发布状态机），Soul/Skill/KB/Tools 是底座上的 asset type，不各自造轮子。
Tech stack: NestJS 11 + TypeORM(PG16/pgvector) · FastAPI Hermes runtime · Next.js 16 · BullMQ · agent/evals/domain golden-set harness · feature-flags(org_specialist 级)
评审基线:
origin/dev@714516a6（2026-07-07），PRD =docs/specs/prd-specialist-value-output.md（2026-07-06 Draft）v2 变更（2026-07-07）: 按 owner 意见重构 Phase 结构——原 v1 按 PRD 资产类型分期（Soul→Skills→KB→Feedback→Runtime→Tools），v2 改为统一底座先行。评审部分（§一、§二）不变。
一、评审结论（TL;DR）
PRD 的方向、分层原则（config is data / edit≠publish / eval 门禁 / 隔离 by construction）与 ADR-033/034/020 对齐良好，建议采纳。但有两类问题：
A. current-state 过期（8 处，见 §2.1），导致工作量分布失真：
- R4（反馈闭环）比 PRD 预估小得多——edit-signal、一键分类、few-shot 复用均已建成或大部分建成；
- R6（Tools）比 PRD 预估大——
tool_specialist_bindings表不存在，注册表是代码内静态字典； - 一个合规矛盾必须最先处理：
correction-refinement.processor今天就在无人工审批自动写 KB，违反 PRD 自己的 OQ-205 默认； - 一个架构决策必须前置：R5 装配器放 Python agent 还是随 ADR-034 E2 迁移线走 API 侧，T5.1 前必须定案。
B. 结构性问题（v2 重点）：PRD §7 按资产类型分期，每期各自建实体 + 版本 + 审计 + 导入 + UI，会产出 4 套异构的配置存储与发布流。五种资产的公共本质是同一个抽象——"版本化、审计、Org×Specialist 作用域、eval 门禁的配置资产"。正确顺序是：统一数据模型与存储 → 统一 admin 管理系统 → 统一装配 → 拓展。底座建一次，资产类型是插件。
二、逐项评审
2.1 Current-state 核查（PRD §3 vs 代码事实）
| # | PRD 声明 | 代码事实 | 对方案的影响 |
|---|---|---|---|
| 1 | "edit-diff in releaseDraft discarded (#3323)" | 已捕获：expert-queue.service.ts:1813 safeEditSignal → wasEdited + editRatio 写入 Expert Message.metadata，并发 PostHog draft_released、触发 autoCorrectFromEdit（#3322）。缺：完整 diff 文本、可查询列、与 category 的联合分析面 | T0.1 从"新建"改"补全" |
| 2 | "correction_embeddings write-only" | 已读：learning.service.ts:331 retrieveSimilarCorrections（#3406）→ maybeInjectCorrectionFewShot few-shot 注入。flag correction_fewshot_enabled 默认 OFF | R4.5 从"建"改"灰度开启 + 质量对照" |
| 3 | "correction→KB processor partial (#303)" | 已完整且越界：LLM 分类 → 去重 → 直接 ingestionService.upload 写 KB，无人工审批 | R4.4 是行为纠偏；现状违反 OQ-205 拟定默认 → Phase 0 止血 |
| 4 | R4.3 "completes the Correction capture UI gap" | 链路已通：ReplyDock 分类选择器 → api.ts → releaseDraft(correctionCategory) | 基本完成，剩验证 + 埋点核对 |
| 5 | "tool_specialist_bindings（ADR-020 row）"为既有设施 | 不存在。现状：specialists.tools[] string 数组 + per-org IntegrationCredential；静态 AGENT_TOOL_REGISTRY（bespoke|nango，无 MCP） | 从"扩展"改"新建"，含 expand-contract 迁移 |
| 6 | Skills "repo bind-mount；M2 计划移到 R2" | M2 通道已存在：agent 启动 GET /v1/internal/org/{slug}/runtime-config，NestJS 下发 soul_md + config_yaml + skills[]（agent/main.py:162-255） | 统一装配的下发通道有现成落点 |
| 7 | "ADR-035 accepted" | ADR-035 是 Proposed；ADR-033 是 Draft；golden-set 格式 OD-13 未决 | eval gate 细节被 OD-13 gate；PRD 需更正 |
| 8 | "agent/evals plumbing, not domain accuracy" | domain harness 已存在：agent/evals/domain/（#3324）golden-set + LLM-as-judge + seeded-KB（retrieval_miss vs hallucination 归因）。judge 未经人工校验、opt-in | eval gate 是"接线"而非"建 harness" |
2.2 确认属实的关键前提
- persona-override 反模式逐字确认：
agent/prompts_loader.py:250-279——system_prompt> 300 字符或含confidence/flag_for_review/{agent_name}/CRITICAL INSTRUCTIONS之一 → 整体替换角色模板。 - 4-key closed union；
systemPrompt无版本无审计；/ops/specialists是 raw textarea；无 abstain 姿态（仅 clarify-first + 置信度自动升级 + 正则 risk）；无装配 trace（仅promptVersion= sha256(SOUL+role template)）；/chat不带 tools manifest。 kb_retrieval_event可经message_idjoin 消息——coverage report 数据基础成立。
2.3 评审新发现（PRD 未覆盖）
| # | 发现 | 处置 |
|---|---|---|
| N1 | BUG：runAgentPipeline 主派发点（conversations.service.ts:3092-3110）未传 specialistPromptTemplateKey，wire 上落到 role fallback——ADR-034 的列在主路径没生效 | 一行级修复 + 回归测试（P0.5） |
| N2 | R5.1 优先级链遗漏两个 已上线的层：active_directives（L0.5，#3692）与 crisis directive | 纳入统一模型设计（P0.3） |
| N3 | 轨道冲突：ADR-034 E2 phase-4.5（已批准）方向是 draft 相关路径迁 LlmService；PRD R5 假设装配器长期在 Python/Hermes | placement 决策进 P0.3，装配 Phase 前定案 |
| N4 | specialists.tools[] → bindings 需 expand-contract 迁移设计 | 纳入 Phase 2 tool_binding 资产接入 |
| N5 | PRD §3 的 8 处过期声明 | P0.7 修订 PRD（en/zh） |
三、统一配置资产模型（方案核心）
3.1 设计动机
五种资产今天的存储彻底异构：Soul = repo SOUL.md + specialists.systemPrompt 裸列；Skills = repo SKILL.md；KB = Haystack + PG（已有版本概念）；Tools = 代码内静态注册表 + specialists.tools[]；模板 = agent/prompts/*.txt 4-key union。PRD 要求它们全部具备同一组能力：结构化 schema、版本、审计、回滚、Org×Specialist 作用域、archetype→instance 继承、edit≠publish、eval 门禁、导入迁移。这组能力实现一次即可。
3.2 底座数据模型（骨架，字段级细化在 P0.3 设计文档）
specialist_config_assets —— 资产主表（隔离矩阵行：Org × Specialist，docstring 必须声明）
id, asset_type soul | skill | kb_golden_answer | kb_domain_rule | tool_binding
scope catalog（SuperAdmin 原型）| org_instance（AM 覆盖，copy-on-materialize）
org_id (nullable for catalog), specialist_id / osa_id
archetype_asset_id (nullable) —— 实例的原型血缘；"upstream changed, pull update?" 的依据（R2.6）
slug, display_name
published_version_id, draft_version_id
source imported_repo | manual | loop_proposal
created_by, created_at, archived_at
specialist_config_versions —— 版本表（所有资产类型共用）
id, asset_id, version_no
content jsonb —— 按 asset_type 的 Zod schema 校验（schema 即独立真相源）
content_r2_key (nullable) —— 超大文本资产走 R2，jsonb 存引用 + hash（Q2 决策落点）
content_hash
author_id, created_at
publish_status draft → publishing(eval running, async) → published | blocked | rolled_back
eval_run_id (nullable), publish_note, published_by, published_at
配套一次性实现：发布状态机（NFR2 异步 eval）、回滚（指针切换到旧 version）、审计（复用现有 audit log，事件 config.publish/config.rollback）、导入框架（dry-run + diff，§8 规则 4）、NFR5 内容安全校验（save 时过 #3054/#3500 规则）。
3.3 三个直接红利
- R4.4 审批队列消失：correction 处理器产出的"提案"就是一条
source=loop_proposal的 draft version，人工审批 = publish 动作。同一状态机、同一审计，OQ-205（"loop 提案、人批准"）由构造保证。 - eval gate 只挂一次：publish 状态机上一个钩子服务所有资产类型，而不是 Soul/Skill/KB 各接一遍 ADR-035。
- 装配 trace 天然可归因：trace 行记 version_id 集合即可精确回答"这条 draft 由哪些资产版本产生"（R5.4），并与 eval run 同键关联。
3.4 防过度抽象护栏（第一性原理的另一半）
- 底座只为这五种已知资产类型设计，字段以 PRD R1–R3/R6 的 schema 需求为准，不做通用配置平台；出现第六种类型前不加扩展点。
- 各 asset_type 的 content schema 用 Zod 定义并同时约束 API 校验与测试（schema-as-source-of-truth，避免 tautology testing）。
- KB 文档本体（K1/K2 上传文档、Haystack 索引）不迁入底座——底座只管"策展型"KB 资产（golden answers、structured rules）；文档继续走既有 ADR-008 管道。
四、Phase 拆解（v2：模型统一 → 管理统一 → 装配统一 → 拓展）
规模：XS < 0.5d · S ≈ 1d · M ≈ 2-4d · L ≈ 1w+。
Phase 0 — 度量基线 + 统一模型设计 + 止血（两周窗口，与 pillar ① 并行）
| ID | 任务 | 规模 | 对应 PRD |
|---|---|---|---|
| P0.1 | [BE] edit-signal 补全：完整 diff 持久化、category 可查询化、backfill-safe（landed 2026-07-07，收窄实现：diff 经 releasedDraftId join 派生而非冗余存文本；两条发送路径链接键统一 + 指标部分索引） | S | T0.1 |
| P0.2 | [BE/FE] draft-quality 指标端点 + /ops dashboard 卡片 | S | T0.2 |
| P0.3 | [DS] 统一配置资产模型设计文档（§三细化到字段级）：五种 asset_type 的 content schema、发布状态机、PG vs R2 split（Q2）、archetype 继承（R2.6）、装配优先级全链（红线 > crisis > active_directives > skill > Soul > 模板 + 分层 token 预算 NFR3）、装配器 placement 定案（N3） | M→L | T0.3（扩容） |
| P0.4 | [DS/BE] OQ-205 定案升 ADR + correction processor 止血（挂 flag 切 propose-only / OFF） | S | T0.4 + R4.4 前置 |
| P0.5 | [BE] 修复 N1：主派发传 specialistPromptTemplateKey + 回归测试 | XS | （新增） |
| P0.6 | [AG/BE] minimal per-turn trace：template key、promptVersion、persona-override 是否触发、KB chunk ids、内容 hash。Org×Specialist 隔离、90 天保留（landed 2026-07-07，收窄实现：落 draft metadata.assembly——promptVersion / templateKeySent / templateUsed / personaOverrideApplied / kbContextProvided / directives 数；KB chunk ids、内容 hash、独立表 + 90 天保留推迟到 P3.4 full trace） | M | T5.4-minimal |
| P0.7 | [DS] 修订 PRD 过期声明（en/zh）+ ADR-035 状态更正 | XS | （新增） |
验收：signal-capture 指标启动（100% released drafts 有 diff+category）；P0.3 文档过评审、D1–D3 决策关闭；processor 自动 ingest 被 flag 控制；主路径 wire 含 template key；每条 draft 有 minimal trace。
Phase 1 — 统一配置底座 + Soul 作为 tracer bullet（"统 一存储与管理"上半场）
底座不空转：以 Soul（最简单的资产）为竖切片，端到端打通"编辑 → 版本 → 发布 → agent 消费"。
| ID | 任务 | 规模 |
|---|---|---|
| P1.1 | [BE] 底座实体 + 迁移（specialist_config_assets / _versions，expand-only）+ 发布状态机 + 回滚 + 审计事件 + NFR5 校验管道 | L |
| P1.2 | [BE] Soul asset_type：Zod content schema（identity/voice/boundaries/languages/sign-off，R1.1）+ CRUD API | M |
| P1.3 | [BE] 导入框架 + Soul 导入器（repo SOUL.md + 现有 systemPrompt，dry-run + diff） | M |
| P1.4 | [FE] Ops admin 系统骨架：资产列表 / 类型化表单编辑器（先 Soul）/ 版本历史 + 回滚 / 发布流 UI（draft→publish 状态可见）。替代 raw textarea（textarea 降级为 advanced 逃生舱，R1.2 弃用准则） | L |
| P1.5 | [BE/AG] 下发通道统一：runtime-config 端点改从底座读 published version（含非 M2 shared agent 路径）；/chat 的 specialist.system_prompt 由底座装配预览同源生成——预览 byte-identical 于 agent 实收（R1 AC2） | M |
| P1.6 | [AG] 移除 persona-override 启发式，挂 per-Specialist cutover flag，shadow 对比（P0.6 的 override 命中率数据定风险面） | M |
| P1.7 | （并行）correction_fewshot_enabled 对 dogfood org 灰度开启，用 P0.2 指标做 ON/OFF 对照 | XS |
Phase 2 — 资产类型接入（"统一存储与管理"下半场）
在已验证的底座上批量接入其余资产类型——每个类型只需：Zod schema + 表单编辑器 + 导入器（+ 该类型特有的消费端）。
| ID | 任务 | 规模 |
|---|---|---|
| P2.1 | [BE/FE] Skill asset_type：trigger + instructions + templates + 结构化红线 + 预留 tools 字段（R2.1）；编辑器 + clone + 绑定；SKILL.md 导入器（Kaito/Acme 种子） | L |
| P2.2 | [BE/FE] catalog archetype → org instance 物化流（copy-on-materialize + "upstream changed, pull?"，R2.6），Soul/Skill 通用 | M |
| P2.3 | [BE/FE] KB 策展资产：kb_golden_answer + kb_domain_rule asset_type（effective_date/audience/jurisdiction 元数据，R3.1/R3.2）+ K2 curation UI（R3.3） | L |
| P2.4 | [BE] golden answers 优先检索路径（检索时 join published versions，R3.1） | M |
| P2.5 | [BE/FE] tool_binding asset_type：新建绑定模型（替代 specialists.tools[]，expand-contract 迁移，N4）+ 绑定配置 UI（R6.2 的存储/管理半场；执行半 场在 Phase 4） | M |
| P2.6 | [BE/FE] KB coverage report（kb_retrieval_event × messages，R3.4）——AM 的策展 to-do list，喂 P2.3 | M |
Phase 3 — 统一装配（R5：底座的运行时消费者）
前置：P0.3 placement 定案。倾向：短期装配器留 agent 侧（prompts_loader 演进为确定性 assembler），输入/trace 契约定义为 runtime 中立，未来可随 ADR-034 E2 整体搬移。
| ID | 任务 | 规模 |
|---|---|---|
| P3.1 | [AG] 确定性 context assembler：固定层序 + 优先级（红线 > crisis > active_directives > skill > Soul > 模板）+ 分层 token 预算 + 红线/身份永不截断（NFR3）+ KB 强制引用（R5.1，吸收 R1.3） | L |
| P3.2 | [AG] trigger 评估引擎：多 skill merge/tie-break、no-match → 角色模板 + abstain 姿态（新机制：标准回复 + queue flag，R5.2/R5.5；#1203 回归测试） | M |
| P3.3 | [AG/BE] 检索编排级联：golden → hybrid K1/K2 → correction few-shot，逐级可按预算跳过（R5.3） | M |
| P3.4 | [AG/BE] full trace：P0.6 扩到 version_id 级（Soul 版本、skill ids+versions、KB chunk ids、逐层预算），join messages/edit-diffs/eval runs（R5.4） | M |
| P3.5 | [AG/BE] 红线 post-draft 检查 + 违规 flag 到 Expert workspace （R2.5 运行时半场） | M |
Rollout（承接 PRD §8）：shadow mode（双路产稿、eval 对比、客户可见仍 legacy）→ per-Specialist cutover flag → dogfood(Eleanora/Acme) → 非关键 → Kaito(Amy) 最后。P0.6 trace 先行是 shadow 归因的前提。
Phase 4 — 拓展：eval 门禁 + 反馈闭环 + Tools 执行（"统一之后的拓展"）
| ID | 任务 | 规模 | 修订说明 |
|---|---|---|---|
| P4.1 | [BE/AG] eval gate：EvalGoldenScenario/EvalRun 实体 + 底座 publish 钩子（一次挂全类型）+ 调 agent/evals/domain harness + judge 人工校验 10–15 case（ADR-035 open item）+ block-on-regression + 审计 override（R4.6） | L | harness 已存在，工作量在接线；依赖 OD-13；runner/看板层可用 Langfuse experiments，见下方调研注记 |
| P4.2 | ✅ 已上线 (2026-07-09) [BE/FE] correction → loop_proposal draft version + 审批（=publish）UI（R4.4）。P4.2a=LoopProposalProducerService、P4.2b=审批 UI、P4.2c=已执行 ADR-037 §Decision 3 的 contract 步骤（删 correction_auto_ingest_enabled flag 与 correction-refinement.processor 直接 ingest 分支；ADR-037 → Accepted）。 | M | 复用底座状态机，无独立审批队列 |
| P4.3 | [BE] few-shot 全量推开（按 P1.7 灰度数据） | S | 原 R4.5，代码已建 |
| P4.4 | [FE/BE] client 👍/👎 + 信号入库（R4.7；Q4 文案先行） | S | |
| P4.5 | [BE/FE] improvement dashboard（acceptance / edit distance / no-hit / golden pass，§6 指标） | M | |
| P4.6 | [BE] MCP tool-source kind + 集成配置（ADR-030 隔离，R6.1） | M | |
| P4.7 | [AG/BE] chat-path 工具暴露：assembler 输出 active skills 声明工具 ∩ bindings（/chat 新增 toolsManifest——现状确认不存在）+ ActionPolicyService 门禁 + 写操作审批项进 Expert queue（R6.3–R6.5；require_expert_approval 决策枝已有） | L | |
| P4.8 | [BE] KB ingestion connectors（R3.5：Notion/Drive/网站定时同步进 K1/K2，同一策展/版本/eval 路径） | M |
P4.1 调研注记（2026-07-07，Langfuse 能否做 CI 门禁）：能——Langfuse Python/JS SDK v3 的 run_experiment(data, task, evaluators, run_evaluators) 就是为 CI 设计的：dataset item 逐条喂给我们自己的 task 回调（执行权在我们的 pipeline），item 级 + run 级 evaluator 打分，结果对象直接在 pytest 里断言阈值；官方另有 langfuse/experiment-action GitHub Action 与 "raise RegressionError on threshold violation" 的 CI/CD 文档模式，也支持 webhook 触发远程实验。边界：(a) 无内建"对比 baseline run 自动判回归"原语——ADR-035 的多轴噪声带回归规则仍需我们自己实现（拉分数自比）；(b) publish 门禁的状态机（阻断发布/审计 override）在我们 API 侧，Langfuse 只是被它调用的 runner/score 层；(c) golden scenarios 含 org 内容，真相源必须留在底座（Org×Specialist 隔离），Langfuse dataset 是同步副本（自托管缓解数据主权，但 project 级隔离粒度不够）。建议架构：golden set 真相源在底座 → publish 钩子把现有 agent/evals/domain harness 包成 run_experiment 的 task → 分数/趋势/run 对比落 Langfuse 看板 → gate 判定 + EvalRun 记录留 API 侧。ADR-035 的 "LangFuse deferred" 决策建议携此证据复议（当时 SDK 的 experiments 能力尚未成熟）。
依赖主线（v2）
P0.3(统一模型+placement) ──► P1.1(底座) ──► P1.2-P1.6(Soul 竖切) ──► P2.x(资产接入)
├──► P3.x(统一装配) ──► P4.7(tools 执行)
P0.1 ──► P0.2 ──► P4.5(dashboard) └──► P4.1(eval gate) ──► P4.2(提案审批)
P0.4(OQ-205+止血) ──► P4.2
P0.6(minimal trace) ──► P3.4(full trace)
OD-13 ──► P4.1
两周窗口切分
必达：P0.1–P0.7 全部。争取：P1.1 底座实体 + 迁移动工（P0.3 定稿后）。容量规则：与 pillar ① 冲突时 pillar ① 优先，可滑的是 Phase 1 启动，P0.x 度量任务不滑。
五、Blocking 决策清单
| # | 决策 | 建议 | Gate |
|---|---|---|---|
| D1 | OQ-205 定案（含 processor 止血策略） | Option A read-only + propose-only 过渡 | P0.4 |
| D2 | 存储 split：PG vs R2 | 结构化字段 PG jsonb（版本表），超大文本 R2 引用 + hash；eval sandbox 只读访问一并定 | P0.3 |
| D3 | 装配器 placement（agent vs API，对齐 ADR-034 E2） | 短期 agent 侧、契约 runtime 中立 | P0.3 → P3.1 |
| D4 | OD-13 golden-set 贡献格式 | ✅ 关闭 (2026-07-09, P4.1)：采纳 light "job + context + rubric" 单元（现有 3 个 golden JSON 即此形态，已 seed 进 eval_golden_scenarios）；结论 fold 进 ADR-035（Accepted），OD-13 entry 已删。full-dialogue transcript 未采纳。 | P4.1 |
| D5 | Q4 client 反馈文案/位置 | Design 跟进，非阻塞 | P4.4 |