weichen/Agent-System-Dev
1
0
Fork 0
Code Issues 1 Pull Requests 7 Actions 2 Packages Projects Releases Wiki Activity
Files
80e5e4559cd8e5e539cf035a70bb04ec1a02065d
Agent-System-Dev/docs/superpowers/plans/2026-10-16-document-visualization-rollout.md
T
weichen d58d5bc1dd Review design docs and freeze cockpit contract decisions 
Why: user approved the four design documents and authorized implementation
(/goal); the plan's section-7 tradeoffs gate the I1 public DTO and had to be
frozen before any implementation unit starts. A read-only audit of the RDM
backend (Agent-System-RDM main 5df66106) supplied the source facts.

Evidence: audit findings recorded in rollout section 7 (tree is doc->section
only, no confidence field, no persisted conflict entity, per-project event seq
complete); review fixes folded into the read-model contract (statReasons,
structuralGap, AssertionSummary); precheck receipt READY imported via
task-resume.

Impact: unlocks I1 implementation in the RDM repo; design deliverable ready
for PR/CI/merge; no business code, pins, database or deployment touched.

Refs: .task/feature-document-visualization-plan.md
2026-10-16 06:25:19 +00:00

8.0 KiB
Raw Blame History

文档驾驶舱可视化分阶段实施与验收计划 r1

状态：待评审；本计划描述后续执行顺序，不构成业务实施授权。真实实现、迁移、部署、模型数据和浏览器验收均为 NOT_RUN。

1. 目标

按四个可独立验证的增量，把既有 RDM 文档树/追溯读取能力提升为项目文档驾驶舱。每个增量都必须保持旧四入口可用，并且不新建写入权威或绕过授权的接口。

2. 依赖与边界

  • 依赖既有 RDM 项目绑定、文档树、关系、事件历史和权限合同；先重新核对当前组件 pin 和接口，再实现。
  • 复用 Frontend/UI 的三栏工作台、@ui tokens、Collapsible 和现有异步状态所有者。
  • 不在本计划内修改模型路由、文档生成/审批、数据库主存储或部署配置。
  • 任何跨仓 gitlink、领域 schema、权限语义或导出行为变化都要单独建立任务和评审记录。

3. 增量分解

I1：聚合读取服务和 DTO

产物：CockpitOverview、TreePage、NodeDetail、来源/历史/影响/冲突分页接口；适配既有 RDM 读取命令；项目/资源/字段级授权；快照 revision、cursor、截断和错误契约。

直接验证：

  • 同一节点在不同项目请求下返回 404/拒绝，不泄露存在性。
  • 统计、树、详情和面板使用相同 snapshotRevision/asOfSeq。
  • 空、部分、受限、过期、上游失败和关系截断都有可判定 DTO。
  • 历史查询不会落在未提交批次中间序号。

停止条件：若现有领域数据无法提供某字段，返回明确 unavailable/partial，不得在服务中生成猜测值。

I2：共享选择与全景投影

产物：项目统计带、文档结构树、全景中央概览、筛选和分页；共享 selectedNodeRef、filterHash、snapshotRevision；过期/刷新提示。

直接验证：

  • 展开、分页、选择和筛选不会让旧响应覆盖新项目或新筛选。
  • 树徽标和统计来自同一快照；刷新不重置用户选择。
  • 无文档、无权限、部分加载和截断状态可读。

停止条件：如果真实数据没有段落级结构，使用实际可用层级并标注 structural gap，不伪造段落。

I3：阅读器与右侧依据/影响面板

产物：连续正文阅读、版本摘要/差异折叠、来源/历史/影响/冲突标签页、全景↔阅读器定位、个人视图偏好。

直接验证：

  • 从全景选择段落切换阅读器后，正文、面板和 URL/内存状态指向同一 nodeRef。
  • 私有来源正文按字段级披露脱敏；受限不显示为空。
  • 乱序事件、断线和后台更新不会抢占滚动位置。
  • 所有折叠、颜色、字号和动效通过设计令牌守护。

停止条件：不增加第四栏或独立关系图；关系仅在右栏局部展开。

I4：组合验证与浏览器验收

产物：跨 RDM/Frontend/UI 的组合测试、权限负例、快照一致性测试、Playwright 场景和设计守护证据。

最小场景集：

  1. 首次进入项目：统计、树、全景可见。
  2. 选中文档→章节→段落：全景与阅读器双向定位。
  3. 来源、历史、影响、冲突展开并正确显示计数/截断。
  4. 未核实来源和冲突状态改变后，所有投影一致。
  5. 过期/断线/部分失败保留旧快照并给出刷新入口。
  6. 未授权项目、节点、来源和下载均失败或脱敏。
  7. 320/390/736/1024/1440 宽度、18px UI 字号、键盘和减少动效。

4. 测试矩阵

类别 必测内容 结果来源
DTO/服务 schema、分页、错误、截断、快照一致性 单元/集成测试；最终以 CI 为准
授权 项目越界、成员/职责、字段级来源披露、下载/导出 后端负例与独立重放
状态 旧响应、乱序事件、上下文切换、断线、过期快照 Frontend store 测试
设计门禁 裸色、私有 keyframes、行内字号、details 禁止 UI/Frontend design-guard
浏览器 双视图、定位、面板、窄屏和键盘 Playwright；真实后端链路另记
组合 固定组件 SHA、make test、make build Dev 当前 HEAD CI/GATE

5. 需求到验收映射

需求 计划增量 验收
DV-R01 I1/I2 项目统计与不可用原因测试 + 首屏浏览器场景
DV-R02 I1/I2 树分页/展开/状态测试
DV-R03 I2/I3 共享选中节点与视图切换场景
DV-R04 I1/I3 四面板分页、计数、截断与定位场景
DV-R05 I1/I2/I3 快照 revision、seq、旧响应丢弃测试
DV-R06 I1/I3/I4 项目/字段/下载授权负例
DV-R07 I3/I4 五宽度、18px、键盘、减少动效浏览器场景
DV-R08 I1/I2/I3 空、部分、过期、失败和截断状态场景

6. 交付门禁

每个增量在实现前需有独立任务卡、当前基线和明确文件范围；实现单元按仓库 AGENT-EXECUTION.md 路由，主模型负责集成和验证。请求审核、合入和完成声明前分别执行 make task-sync，命令输出通过 make evidence 写入任务卡。作者本地测试只能标 SELF；精确 HEAD 的 CI 标 GATE，独立复跑标 REPLAY。

7. 契约决策（已冻结 2026-10-16）

用户于 2026-10-16 评审四份文档并授权进入实施（/goal 按照方案开始实施），本节四项取舍由本轮评审冻结。依据为实施前对 RDM 后端（独立仓 Agent-System-RDM，main 5df66106）的只读源审计；后续领域数据演进时按契约 §9 版本规则扩展，不在本版内回改。

  1. 完成度分母只统计已存在的文档/章节节点。 现状：文档树叶节点即章节 Section（internal/domain/doctree.go:40-51），Section.Require 标记必选章节，但“模板要求而未实例化的章节”缺少已核实的权威数据源；纳入分母会引入猜测值，触碰“不得生成猜测值”停止条件。树内结构性缺失继续由 missingChildCount 与 structuralGap 承载；模板级完成度留待后续增量，且须先核对 Doc.Template 的实例化语义。
  2. 置信度由读模型固定为 high/medium/low/unknown，适配器不猜测。 现状：领域仅有来源溯源枚举 human|rule|model（internal/domain/eventlog.go:53-60），无 confidence 数值；核验语义仅存在于法规双通道 RegSource.Verified()（internal/domain/regcheck.go:13-27）。v1 适配规则：只有可复核证据（如法规来源已核验）才产出 high，其余一律 unknown；禁止把溯源枚举直译为置信等级。
  3. 首期冲突只投影领域现有检测视图，不做字段级断言。 现状：无持久化冲突实体；冲突是 fc.Detector 对切片对的运行时碰撞检测（internal/domain/fc/collide.go:27-53），裁决落为 supersedes 追溯边并关闭成对 pending 项（collide.go:125-145）。v1 映射：pending 碰撞 → open；存在 supersedes 裁决 → resolved/superseded（按实际边语义）；acknowledged 首期不产生。字段级断言冲突须等领域先有字段级断言登记，属后续领域增量。
  4. 全景首屏只显示章节概览与统计，不显示段落摘要。 现状：文档树只有 doc→section 两级，无段落层（internal/domain/domain.go:23-35）；且首屏共享面上的正文摘要在无逐字段披露检查时会扩大敏感内容暴露。段落/正文摘要在选中节点与阅读器内按权限展示。

I1 的公开 DTO 实现自本节冻结起解锁；实施落点为 RDM 后端仓（聚合读取服务与命令），Dev 仓只承载文档、组合 pin 与后续前端集成。

8. 当前状态与下一步

四份文档已于 2026-10-16 评审通过，§7 四项决策冻结，实施授权已由用户给出（/goal 按照方案开始实施）。I1–I4、测试、CI、部署和业务验收仍为 NOT_RUN。下一步：合入本设计 PR 后，在 RDM 后端仓为 I1（聚合读取服务与 DTO）建立实施任务并按 AGENT-EXECUTION.md 拆分派发；I1 适配目标为 rdm.inspect.* 既有事实与 §7 冻结的映射规则。

Reference in New Issue View Git Blame Copy Permalink