# 重构观察台

观察台是 OpenCode 重构流程的可选 Web 窗口。它读取同一个 PaaS review_id，自动同步结果；候选选择、执行确认、质量审查仍在 CLI `/refactor` 完成。

## 打开

在已有重构任务的 OpenCode 会话中输入：

> 打开当前重构任务的可视化看板，展示真实分析与执行证据，不新建任务。

工具入口为 `software_review` 的 `dashboard`（`web` 为同义入口）。`open` 仍返回 CLI，不强制跳网页。看板只绑定一个任务；新建任务或下一批后，用新 review_id 打开对应看板。

也可以在已设置 AGENTPAAS_URL、AGENTPAAS_API_KEY 的环境中运行：

```sh
bun script/serve-software-dashboard.ts --review <32位审阅编号>
```

可选 --port 固定本机端口。分离审阅服务通过 AGENTPAAS_SOFTWARE_REVIEW_URL 配置，必须与 PaaS 同主机、同协议。凭证不要写入命令行或 URL。

## 五个视图

| 视图 | 真实来源 | 边界 |
| --- | --- | --- |
| 项目总览 | repository_summary、coverage、ontology.statistics | 冻结清单中的目录统计，不以候选文件代替全仓库；未测量 LOC 不编造 |
| 影响路径 | 候选 ontology_context 与源码摘录 | 静态可达关联不是实际动态调用；截断明确显示 |
| 前后变化 | proposal、execution.result、changes.patch、comparison.json | 计划片段与实际补丁分开；线索消失不等于业务缺陷已解决 |
| 测试结果 | 当前 generation 的 evidence.checks | 通过、失败、跳过、未知分别显示；缺报告不计通过 |
| 剩余问题 | 候选决策、未解析引用、规则状态、quality_review | 搜索筛选只影响展示，人工意见按原文展示 |

看板从服务端 analysis_scope 读取分析范围和适配器名称，候选类型与节点标签允许扩展。目录图按冻结清单中的所有文件统计，文件扩展名分布可展开。现有分析执行器仍遵循平台 Java/Maven 支持边界；界面兼容 Python/TypeScript 数据并不表示这些语言已获执行支持。旧 PaaS 无 repository_summary 时显示未提供，不把未知当成零。目录分组不是已验证的业务模块；文件类型统计不是执行或测试支持声明。

## 同步与权限

- 本机回环端口，每 3 秒同步原任务；隐藏页面暂停轮询。关闭页面不会取消任务。
- 断线保留上次快照并明确告知；版本不一致时重新读取证据，不拼成一次验收。
- API key 仅在客户端代理中使用，不进入 HTML、浏览器存储或 URL。
- 看板模式拒绝所有非 GET 请求，固定审阅编号并保留 PaaS 租户鉴权。
- Host、页面 token、CSP 与输出转义限制访问；源码和日志作为文本展示。
- 证据按需、分页读取，由 PaaS 验证证据 token。无 CDN 或第三方页面依赖。
- 本机地址不能作为企业外网分享链接；对外发布需独立配置认证和访问范围。

## 验证

在 packages/opencode 下执行：

```sh
bun test test/tool/software-review.test.ts test/tool/software-dashboard.test.ts
bun run typecheck
```

浏览器验收脚本为 script/check-software-dashboard.mjs。DASHBOARD_URL 指向已有完整证据的真实看板；PLAYWRIGHT_MODULE、CHROMIUM_EXECUTABLE 指向本机工具，DASHBOARD_OUTPUT 指定截图目录。检查真实五视图、补丁与响应布局；另在独立浏览器上下文中模拟空结果、测试失败、版本更新、恶意文本和断线。不修改真实任务。

## 连续过程与可读性

- 分析中显示服务端实测批次进度与本体关联阶段；未完成的候选数显示待确定。
- 执行中即使审阅 revision 不变，也刷新本任务的证据索引，用 token 判断内容更新。
- 质量退回直接展示 reason；测试状态翻译为中文，同时展示实际失败原因。
- 候选列表每页 20 条，可完整翻页，筛选或搜索会回到第一页。状态刷新保留搜索输入、焦点及已展开材料。
- `script/check-software-dashboard.mjs` 覆盖真实任务五视图，以及合成状态的实时证据、退回理由、65 条候选分页、搜索焦点和分析进度。不同语言的 UI 测试只验证数据适配，不宣称后端已支持对应语言重构。

证据分页从第一页固定 manifest token；实时刷新不会切换正在阅读的文件版本。期间证据更新会要求重新打开文件，不能拼接旧页与新页。取消或中断分析时，阶段停在“构建本体”，并提示重新分析或查看已创建的后续任务。

## 本体关系与智能体规划同步

影响页区分上游影响和下游依赖，未解析引用可展开目标、源码位置和原因；不把外部库未解析当作缺陷。旧任务缺少这些字段时显示未采集，新字段不由前端推算。

OpenCode `software_review/ontology` 的 `relation_view` 提供 `impact`、`dependencies`、`unresolved` 三类候选视图，分页与服务端截断分别标明。CLI 规划草稿引导智能体读取同一任务 context/source，再按上述关系组织“改动点、关系证据、保持条件、验证依据”。看板保持只读，选择、确认、质量审查仍在 CLI；不另建一套审批状态。