ai-delivery-workflow 0.2.2

package/docs/VIEWER-MAINTENANCE.zh-CN.md

@@ -0,0 +1,373 @@
+# 工作流物料查看器维护指南
+
+> 适用对象：维护 `ai-delivery-workflow` 发行仓库的开发者和 AI  
+> 目标：下次修改查看器时，能够快速定位权威源码、理解契约并完成验证  
+> 配套使用文档：[VIEWER-USER-GUIDE.zh-CN.md](VIEWER-USER-GUIDE.zh-CN.md)
+
+## 1. 下次修改前先读这里
+
+查看器的权威源码只有：
+
+```text
+skills/ai-delivery-orchestrate/
+  assets/project-template/
+    .workflow/tools/viewer/
+```
+
+以下位置都是派生副本，不得作为发行源码修改：
+
+- 任意业务项目的 `.workflow/tools/viewer/`；
+- 本仓库 `.tmp/viewer-demo/.workflow/tools/viewer/`；
+- AppData、`/tmp` 或系统临时目录中的 QA 项目；
+- `.workflow/delivery/runtime/backups/` 中的历史副本。
+
+修改后由 `lib/project-installer.mjs` 把权威目录复制到目标项目。只修改已安装副本会导致下一次 `init --force` 丢失改动。
+
+开始任务时建议先向 AI 提供：
+
+```text
+请先阅读 docs/VIEWER-MAINTENANCE.zh-CN.md 和
+docs/VIEWER-USER-GUIDE.zh-CN.md，再修改项目内工作流物料查看器。
+权威源码位于 skills/ai-delivery-orchestrate/assets/project-template/
+.workflow/tools/viewer/，不要修改 `.tmp/viewer-demo` 或业务项目中的派生副本。
+完成后执行维护指南中的完整验证清单。
+```
+
+## 2. 不可破坏的产品约束
+
+除非需求明确变更并同步更新测试、使用指南和安全评审，否则保持：
+
+1. `init` 自动安装查看器，用户不需要单独安装前端依赖。
+2. 不修改业务项目 `package.json`。
+3. 只使用 Node.js 18+ 标准库和浏览器原生 API。
+4. 默认监听 `127.0.0.1:4173` 并打开浏览器。
+5. 只读当前项目 `.workflow/`。
+6. 不提供写入、审批、归档、部署或生产操作 API。
+7. 自进化视图只读取 `.workflow/evolution/index.yaml` 和 Git 跟踪的治理物料；不得读取 runtime 原始反馈或提供扩展批准、启停和回退接口。
+7. 拒绝路径穿越，不跟随 `.workflow/` 中的符号链接。
+8. 文本预览上限 2 MiB，单次扫描上限 10,000 个文件。
+9. 桌面保留节点、物料表、详情三栏；移动端保留同一核心审阅流程。
+10. 面向用户的文案默认简体中文。
+
+## 3. 架构
+
+```mermaid
+flowchart LR
+    I["ai-delivery init"] --> P["project-installer.mjs"]
+    P --> V["目标项目 .workflow/tools/viewer"]
+    S["启动脚本"] --> N["server.mjs"]
+    N --> W["目标项目 .workflow"]
+    N --> A["只读 HTTP API"]
+    N --> R["public 静态资源"]
+    A --> B["浏览器 app.js"]
+    R --> B
+    B --> U["节点 / 表格 / 详情 / 预览"]
+```
+
+运行时没有数据库和构建步骤：
+
+1. 启动脚本执行同目录 `server.mjs`。
+2. 服务端根据启动位置确定默认项目根，也接受 `--project`。
+3. 浏览器加载 `index.html`、`styles.css` 和 `app.js`。
+4. `app.js` 请求 `/api/catalog`。
+5. 服务端即时扫描 `.workflow/`、计算元数据并返回目录。
+6. 用户选择物料后，前端按类型请求 `/api/document` 或 `/api/file`。
+
+## 4. 文件职责
+
+| 文件 | 职责 | 常见修改场景 |
+| --- | --- | --- |
+| `server.mjs` | 参数、扫描、元数据推导、安全边界、HTTP API、静态服务 | 新文件类型、新状态、节点映射、API、安全限制 |
+| `public/index.html` | 应用壳、可访问语义、控件和详情区 DOM | 新控件、新字段、新面板 |
+| `public/app.js` | 前端状态、筛选、渲染、关系跳转和预览 | 新交互、新预览器、新筛选字段 |
+| `public/styles.css` | 设计令牌、桌面/移动布局、状态和预览样式 | 视觉、密度、响应式、可访问状态 |
+| `start.cmd` | Windows CMD 入口 | 参数透传或 Node 启动兼容 |
+| `start.ps1` | PowerShell 入口 | PowerShell 启动兼容 |
+| `start.sh` | macOS/Linux 入口 | POSIX Shell 启动兼容 |
+| `lib/project-installer.mjs` | 安装、冲突检测、备份、清单和 doctor | 安装位置、受管文件、诊断规则 |
+| `verification/workflow-viewer.test.mjs` | 服务端、HTTP 边界和语法回归 | 每次行为变更必须同步 |
+
+相关文档入口：
+
+- `README.md`：最短启动入口；
+- `docs/PROJECT-MANUAL.zh-CN.md`：整体流程中的查看器定位；
+- `docs/VIEWER-USER-GUIDE.zh-CN.md`：完整用户操作；
+- `docs/FILE-REFERENCE.zh-CN.md`：发行文件职责。
+
+## 5. 安装生命周期
+
+`lib/project-installer.mjs` 将整个查看器目录视为受管目录：
+
+1. 目标不存在：复制权威目录。
+2. 目标摘要相同：不执行动作。
+3. 目标摘要不同且未传 `--force`：报告冲突并停止。
+4. 目标摘要不同且传入 `--force`：先备份，再整体替换。
+5. 安装清单记录 `viewer_root` 和三类 `viewer_start`。
+6. `doctor` 检查服务端、前端资源和三类启动脚本是否齐全。
+
+不要把运行日志、缓存、用户偏好或数据库写入受管查看器目录，否则会造成无意义的摘要冲突。当前查看器没有持久状态。
+
+## 6. 服务端契约
+
+### 6.1 启动参数
+
+| 参数 | 环境变量 | 默认值 |
+| --- | --- | --- |
+| `--host` | `AI_DELIVERY_VIEWER_HOST` | `127.0.0.1` |
+| `--port` | `AI_DELIVERY_VIEWER_PORT` | `4173` |
+| `--project` | 无 | 查看器目录向上两级 |
+| `--no-open` | 无 | 默认自动打开 |
+
+端口必须是 `1..65535` 的整数。
+
+### 6.2 HTTP API
+
+所有接口只接受 `GET`。
+
+| 路径 | 返回 | 边界 |
+| --- | --- | --- |
+| `/api/health` | 服务状态和项目根 | 不读取文档正文 |
+| `/api/catalog` | 项目、版本、发布、分组节点、物料、生产/研发线摘要和计数 | 每次请求重新扫描 |
+| `/api/document?path=...` | UTF-8 文本内容 | 仅 `.workflow/`，最大 2 MiB，扩展名白名单 |
+| `/api/file?path=...` | 图片二进制 | 仅 `.workflow/`，仅 GIF/JPEG/PNG/WebP |
+| `/` 及静态路径 | 内置前端 | 只能读取 `public/` 内文件 |
+
+新增 API 时必须继续满足：
+
+- 默认拒绝非 `GET`；
+- 使用结构化 JSON 错误；
+- 对所有文件路径同时检查前缀和解析后的真实边界；
+- 不把项目根之外的绝对路径返回为可读取资源；
+- 不放宽 CSP 来规避前端实现问题。
+
+### 6.3 目录数据
+
+`/api/catalog` 当前 `schema_version` 为 `1`，顶层字段为：
+
+```text
+schema_version
+scanned_at
+project
+iterations
+nodes
+documents
+counts
+truncated
+```
+
+每个 `document` 的稳定字段包括：
+
+```text
+path, title, file_name, extension, type,
+node_id, iteration_id, status, declared_status,
+version, artifact_id, standards,
+modified_at, size_bytes, checksum, git_status,
+preview_kind, previewable, inbound, outbound
+```
+
+变更、删除或重命名字段属于前后端契约变更。必须同步修改 `app.js`、测试、文档，并评估是否提升 `schema_version`。
+
+## 7. 推导规则
+
+### 7.1 项目和迭代
+
+- 项目 ID、名称来自 `.workflow/delivery/project.yaml`；
+- 当前迭代优先读取 schema 2 的 `development_state.scope_id`，旧 schema 才回退到顶层 `iteration_id`；当前发布优先读取 `release_state.scope_id`；
+- 其次读取 `project.yaml` 的 `current_iteration_id`；
+- 最后回退到扫描结果中排序靠后的迭代 ID。
+- 当前生产版本、生产 release ID 和累计研发版本优先读取 `workflow-state.yaml` 的审计字段；`project.yaml` 同名字段只作旧项目兼容回退。
+
+### 7.2 节点
+
+已登记物料优先使用 `artifact-registry.yaml` 的 `node`。未登记文件再从 `.workflow/iterations/<iteration-id>/<node-id>/` 推导；长期产品、架构、体验、规范和治理目录有固定映射；最后才读取正文 `node`、`node_id`、`stage`。
+
+`walkWorkflow()` 必须忽略 `.gitkeep` 和整个 `.workflow/delivery/runtime/` 子树。占位文件只用于跨 clone 保留空目录；runtime 只保存本机活动状态、心跳、锁和安装备份。两者都不是交付物，也不得进入迭代、发布、节点数量或进度计算。
+
+研发、发布、历史节点定义和别名都在 `server.mjs` 顶部。增加流程节点时应同时检查：
+
+- `NODE_DEFINITIONS`；
+- `NODE_ALIASES`；
+- 总流程手册和编排 Skill；
+- 桌面进度轨密度和移动端横向节点栏；
+- 审计样例和节点数量断言。
+
+### 7.3 状态
+
+Git 变更优先显示为“已变更”。否则已登记物料使用 `artifact-registry.yaml` 的 `status`，未登记文件再读取：
+
+```text
+status
+decision
+version_status
+state
+```
+
+状态映射位于 `STATUS_META` 和 `normalizeStatus()`。新增值时要明确 key、中文标签和语义色，不要只在前端添加颜色。
+
+后端必须覆盖正式状态 CLI 可产生或正式物料可登记的全部状态。尤其是 `frozen`、`immutable`、`deployed`、`archived` 必须映射为成功；`review-draft`、`superseded` 为中性；`pending-approval`、`rolled-back` 为警告。回归测试应使用 `/api/catalog` 或 `buildCatalog()` 验证节点计数，而不是只检查前端颜色。
+
+### 7.4 标题、版本和 ID
+
+- Markdown 标题优先使用第一个一级标题；
+- 已登记物料的版本和 ID 优先使用注册表，未登记文件再从结构化文本依次尝试已定义字段；
+- 没有值时回退为文件名；
+- 当前字段提取是面向多种文本格式的受控标量识别，不是完整 YAML/JSON 解析。
+
+注册表使用安装在 `.workflow/tools/state/vendor/yaml/` 的结构化解析器；发行仓库测试回退到包依赖。其他正文仍采用受控标量识别。不能用复杂正则模拟完整数据格式。
+
+### 7.5 上下游关系
+
+服务端只把正文中能解析且真实存在的文件路径登记为关系：
+
+- 以 `.workflow/` 开头的项目路径；
+- 以 `./` 或 `../` 开头的相对路径。
+
+推导得到的正向引用是 `outbound`，反向索引是 `inbound`。自然语言中的物料名称不会自动建立关系。
+
+## 8. 前端状态和交互
+
+`app.js` 使用一个内存状态对象保存目录、物料、筛选结果、当前节点、选中文档和预览模式。
+
+核心调用顺序：
+
+```text
+loadCatalog
+  -> initializeCatalog
+  -> applyFilters
+  -> renderTable / renderNodes / renderProgress
+
+selectDocument
+  -> 填充元数据与关系
+  -> 请求预览
+  -> renderPreview
+```
+
+修改交互时保持：
+
+- 筛选结果、左侧节点和进度统计使用同一目录状态；
+- 重新扫描时尽可能保留当前选择；
+- 文档切换存在异步请求时，旧响应不得覆盖新选择；
+- 所有文档正文在插入 HTML 前转义；
+- Markdown 支持是受控轻量预览，不执行文档中的 HTML 或脚本；
+- 控件有可见焦点，表格行支持键盘打开；
+- `hidden` 状态必须在 CSS 中保持互斥，避免空状态覆盖详情。
+
+## 9. 样式和响应式约束
+
+当前断点：
+
+| 范围 | 布局 |
+| --- | --- |
+| 大于 `1180px` | 完整三栏和顶部扫描信息 |
+| `901px..1180px` | 收窄节点栏、详情栏和搜索 |
+| `621px..900px` | 详情变为右侧抽屉，表格隐藏次要列 |
+| 小于等于 `620px` | 顶部两行 Grid、节点横向滚动、两列表格 |
+
+重要实现约束：
+
+- `.app-shell` 和 `.document-workspace` 必须使用 `minmax(0, 1fr)` 的可收缩列；
+- 固定格式区域使用稳定行列尺寸，避免动态文本改变布局；
+- 页面本身不得产生横向滚动；节点栏、表格或预览可在自身边界内滚动；
+- 详情空状态和正文状态不得同时显示；
+- 390px 宽度下刷新按钮、迭代、搜索、筛选和状态列必须可见；
+- 不使用营销页、装饰性卡片堆叠或与工作台无关的视觉元素。
+
+## 10. 按需求定位修改入口
+
+| 需求 | 主要文件 | 必须补充的验证 |
+| --- | --- | --- |
+| 增加物料字段 | `server.mjs`、`app.js`、`index.html` | catalog 单测、详情截图 |
+| 增加文件预览类型 | `server.mjs`、`app.js` | MIME/边界测试、真实预览 |
+| 增加筛选器 | `index.html`、`app.js`、`styles.css` | 筛选状态和移动端 |
+| 调整状态规则 | `server.mjs`、`styles.css` | 状态别名、色调和计数 |
+| 调整节点 | `server.mjs`、流程文档/Skill | 节点数量、进度轨和审计样例 |
+| 调整安全限制 | `server.mjs` | 路径穿越、方法、大小和类型测试 |
+| 调整安装位置 | `project-installer.mjs`、文档 | init、force 备份、doctor、manifest |
+| 视觉或响应式修改 | `styles.css`，必要时 HTML | 桌面、390px、详情打开状态 |
+
+## 11. 标准修改流程
+
+1. 阅读本指南、使用指南和相关源码。
+2. 明确需求是否改变只读、安全、安装或 catalog 契约。
+3. 只修改权威模板目录和发行源码。
+4. 先增加或更新 `verification/workflow-viewer.test.mjs`。
+5. 执行语法和自动化测试。
+6. 使用 CLI 初始化一个隔离项目，不能只从模板目录直接测试。
+7. 向隔离项目写入代表性的 `.workflow/` 物料。
+8. 执行 `doctor`。
+9. 从隔离项目实际运行 `start.cmd`、`start.ps1` 或 `start.sh`。
+10. 在桌面和 390px 移动视口验证加载、筛选、详情和预览。
+11. 检查控制台错误、页面溢出和路径读取边界。
+12. 更新 README、用户指南、维护指南和文件参考。
+13. 执行 npm 打包检查，确认新文件进入发行包。
+14. 删除临时项目、浏览器配置和诊断脚本；可保留最终截图作为审阅证据。
+
+## 12. 自动化验证
+
+仓库根目录执行：
+
+```powershell
+node --check skills/ai-delivery-orchestrate/assets/project-template/.workflow/tools/viewer/server.mjs
+node --check skills/ai-delivery-orchestrate/assets/project-template/.workflow/tools/viewer/public/app.js
+node --test verification/workflow-viewer.test.mjs
+npm test
+node --test verification/checkpoint-task-state.test.mjs
+npm run audit:verify
+npm pack --dry-run --json --cache .tmp/npm-cache
+```
+
+安装验证：
+
+```powershell
+node bin/ai-delivery.mjs init E:\path\to\isolated-project
+node bin/ai-delivery.mjs doctor E:\path\to\isolated-project
+```
+
+升级冲突验证至少覆盖：
+
+```powershell
+node bin/ai-delivery.mjs init E:\path\to\isolated-project --dry-run
+node bin/ai-delivery.mjs init E:\path\to\isolated-project --force
+```
+
+浏览器验证的最小流程：
+
+```text
+打开首页
+-> 确认项目、迭代、节点和物料非空
+-> 搜索一个已知标题
+-> 打开唯一结果
+-> 确认元数据、关系、checksum 和预览
+-> 切换到 390x844
+-> 确认无页面横向溢出，主要控件和状态列可见
+-> 确认控制台没有相关错误
+```
+
+## 13. 完成定义
+
+一次查看器修改只有同时满足以下条件才算完成：
+
+- 权威模板而非派生副本已修改；
+- 新行为有自动化测试；
+- `init`、`doctor` 和启动脚本真实可用；
+- `.workflow/` 外文件仍不可读取；
+- 桌面与移动端核心流程均通过；
+- 控制台无未解释错误；
+- 文档和文件索引已同步；
+- npm dry-run 包含全部必要文件；
+- 临时 QA 资源已清理。
+
+## 14. 当前基线
+
+截至本指南建立时：
+
+- 包版本：`0.2.0`；
+- 流程导航：治理、13 个研发节点、11 个发布节点和按需显示的历史兼容节点；
+- 支持预览：Markdown、CSV、JSON、YAML、JSONL、TOML、文本、HTML 原型源码和图片；
+- 文本预览限制：2 MiB；
+- 扫描限制：10,000 个文件；
+- 默认地址：`http://127.0.0.1:4173`；
+- 自动化基线：37 个仓库测试，其中 3 个查看器定向测试；
+- 视觉基线：桌面三栏工作台，移动端节点横栏、两列表格和详情抽屉。
+
+若这些数字或契约发生变化，必须在同一次修改中更新本节。

package/docs/VIEWER-USER-GUIDE.zh-CN.md

@@ -0,0 +1,235 @@
+# 工作流物料查看器使用指南
+
+> 适用对象：使用 AI Delivery Workflow 的产品、研发、测试、运维和审阅人员  
+> 适用范围：由 `ai-delivery init` 安装到当前项目的 `.workflow/tools/viewer/`  
+> 数据边界：只读当前项目 `.workflow/`
+
+## 1. 查看器解决什么问题
+
+查看器把 `.workflow/` 中按计划版本、发布和节点分散保存的物料汇总为一个本地工作台，用于：
+
+- 分别查看研发流程与独立发布流程、当前生产版本、累计研发线、发布目标和物料数量；
+- 按状态、类型、节点、Git 变更或关键字筛选；
+- 查看物料路径、版本、更新时间、SHA-256 和适用规范；
+- 跟踪文档中可解析的上游、下游文件引用；
+- 预览 Markdown、CSV、JSON、YAML、JSONL、TOML、文本和图片；
+- 在手机或窄屏浏览器中快速审阅。
+
+查看器没有写接口。批准、修改、归档和生产操作仍由对应 Skill 和正式流程完成。
+
+查看器同时提供只读“自进化控制环”摘要，展示反馈、待处理提案、trial、active、高风险生效、回退和 Hook 结果。自进化批准、启停和回退仍必须通过 `$ai-delivery-evolve-workflow` 与 `.workflow/tools/evolution/evolve.mjs` 完成。
+
+## 2. 安装
+
+在目标项目根目录执行：
+
+```bash
+npx ai-delivery-workflow@latest init .
+npx ai-delivery-workflow@latest doctor .
+```
+
+安装完成后会出现：
+
+```text
+.workflow/tools/
+  viewer/
+    server.mjs
+    start.cmd
+    start.ps1
+    start.sh
+    public/
+```
+
+查看器只安装到当前项目，不会写入用户全局 Codex 或 agent skill 目录，也不会修改业务项目的 `package.json`。
+
+运行环境要求：Node.js 18 或更高版本。
+
+## 3. 启动和停止
+
+### 3.1 Windows CMD
+
+在项目根目录运行：
+
+```powershell
+.\.workflow\tools\viewer\start.cmd
+```
+
+### 3.2 Windows PowerShell
+
+```powershell
+.\.workflow\tools\viewer\start.ps1
+```
+
+### 3.3 macOS 或 Linux
+
+```bash
+sh ./.workflow/tools/viewer/start.sh
+```
+
+默认行为：
+
+- 监听 `127.0.0.1:4173`；
+- 自动打开默认浏览器；
+- 扫描启动脚本所在项目的 `.workflow/`；
+- 在终端输出项目路径和访问 URL。
+
+在启动终端中按 `Ctrl+C` 停止服务。
+
+## 4. 常用启动参数
+
+启动脚本会把参数原样传给 `server.mjs`。
+
+| 需求 | 示例 |
+| --- | --- |
+| 不自动打开浏览器 | `.\.workflow\tools\viewer\start.cmd --no-open` |
+| 更换端口 | `.\.workflow\tools\viewer\start.cmd --port 4180` |
+| 指定监听地址 | `.\.workflow\tools\viewer\start.cmd --host 127.0.0.1` |
+| 临时查看另一项目 | `node .\.workflow\tools\viewer\server.mjs --project E:\path\to\project` |
+
+也可使用环境变量：
+
+| 环境变量 | 默认值 | 作用 |
+| --- | --- | --- |
+| `AI_DELIVERY_VIEWER_HOST` | `127.0.0.1` | 监听地址 |
+| `AI_DELIVERY_VIEWER_PORT` | `4173` | 监听端口 |
+
+显式命令行参数优先于环境变量。
+
+不要把监听地址改成 `0.0.0.0` 后直接暴露到不可信网络。.workflow 可能包含架构、环境、发布和生产证据。
+
+## 5. 界面说明
+
+### 5.1 顶部工具栏
+
+- 项目名称来自 `.workflow/delivery/project.yaml`；
+- 迭代选择器用于切换当前或历史迭代；
+- 搜索框匹配标题、路径、物料 ID、类型、节点和规范 ID；
+- “刷新”重新扫描磁盘，不需要重启服务；
+- 最近扫描时间表示本次目录扫描完成时间。
+
+可使用 `Ctrl+K` 或 `Command+K` 聚焦搜索框。
+
+### 5.2 工作流节点
+
+左侧按“治理、研发流程、发布流程、历史兼容”分组展示节点。新流程包含 13 个研发节点和 11 个发布节点；只有存在历史物料时才显示旧发布节点。
+
+点击节点可以筛选，再次点击同一节点可取消筛选。移动端使用横向节点栏。
+
+### 5.3 研发与发布进度
+
+顶部摘要显示当前生产版本、累计研发线、待发布版本数、发布目标和发布模式。当前生产版本、生产 release ID 和累计研发版本优先读取 `workflow-state.yaml` 的审计字段，旧 `project.yaml` 字段仅作兼容回退。下方两条独立轨道分别计算研发与当前发布进度。只有节点存在物料且这些物料全部为成功状态时，节点才计为完成；`frozen`、`immutable`、`deployed` 和 `archived` 均属于正式成功状态。
+
+进度百分比用于快速浏览，不替代 Gate、审批记录或版本归档证明。
+
+### 5.4 筛选和物料表
+
+支持：
+
+- 状态；
+- 文件类型；
+- 节点；
+- 仅看 Git 变更；
+- 全文关键字。
+
+点击“重置”清空筛选。表中点击一行会打开详情；键盘聚焦行后可使用 `Enter` 或空格打开。
+
+### 5.5 详情和预览
+
+详情区显示：
+
+- 节点、类型、版本、物料 ID、更新时间和大小；
+- Git 状态和迭代；
+- 上游、下游文件引用；
+- SHA-256；
+- 正文中识别到的 `STD-*` 规范 ID；
+- 格式化预览或原文。
+
+点击上游或下游引用可以跳转到对应物料。按 `Escape` 或点击关闭按钮关闭详情。
+
+## 6. 查看器如何识别物料
+
+查看器递归扫描当前项目 `.workflow/`，符号链接不会被跟随。用于让 Git 保留空目录的 `.gitkeep` 是结构占位文件，不会出现在物料、迭代、发布或节点计数中。被 Git 忽略的 `.workflow/delivery/runtime/` 保存本机活动任务、心跳、锁、Evolution 原始队列和安装备份，也不会作为正式物料扫描；`.workflow/evolution/` 和 `.workflow/extensions/` 中的脱敏治理物料会正常显示。
+
+常用识别规则：
+
+| 信息 | 优先来源 |
+| --- | --- |
+| 项目 | `.workflow/delivery/project.yaml` |
+| 当前迭代 | `workflow-state.yaml` 的 `development_state.scope_id`；旧 schema 回退到顶层 `iteration_id`，最后才使用 `project.yaml.current_iteration_id` |
+| 生产与累计研发身份 | `workflow-state.yaml` 的 `production_version_id`、`production_release_id`、`latest_line_version_id`；其次才是 `project.yaml` 兼容字段 |
+| 节点 | 已登记物料优先使用 `artifact-registry.yaml` 的 `node`；否则使用路径或正文字段 |
+| 标题 | Markdown 一级标题，其次是 `title`、`name`、物料 ID，最后是文件名 |
+| 状态 | Git 变更优先；已登记物料其次使用注册表 `status`；最后读取正文状态字段 |
+| 版本 | 已登记物料优先使用注册表 `version`；否则读取正文版本字段 |
+| 物料 ID | 已登记物料优先使用注册表 ID；否则读取正文 ID 字段 |
+| 规范 | 正文中的 `STD-[A-Z0-9-]+` |
+| 关系 | 正文中指向已存在 `.workflow/...` 文件的路径引用 |
+
+建议在正式物料中使用稳定路径和明确字段。只写自然语言而没有路径或字段时，查看器不会猜测关系和状态。
+
+查看器不会修改状态。需要更新正式状态时使用 `.workflow/tools/state/state.mjs`，详见[正式状态 CLI 使用指南](STATE-CLI-USER-GUIDE.zh-CN.md)。
+
+## 7. 文件和预览限制
+
+- 单次最多扫描 10,000 个文件，超过后界面会提示结果已截断；
+- 文本预览上限为 2 MiB；
+- 大于 2 MiB 的文本仍可出现在目录中，但不能在线预览；
+- 图片支持 GIF、JPEG、PNG 和 WebP；
+- PDF 可被登记和筛选，但当前不提供内嵌预览；
+- CSV 格式化预览最多展示前 200 行；
+- 查看器按请求重新生成目录数据，不维护独立数据库。
+
+## 8. 安全边界
+
+查看器具备以下固定边界：
+
+- 仅接受 HTTP `GET`；
+- 文档和图片读取路径必须位于当前项目 `.workflow/`；
+- 拒绝 `..` 等路径穿越；
+- 静态资源只能来自内置 `public/`；
+- 默认只绑定本机回环地址；
+- 静态页面带 CSP、`nosniff` 和无引用来源策略；
+- 不提供修改、上传、删除、审批或部署接口。
+
+浏览器能看到的内容仍受当前操作系统用户权限控制。不要在不可信机器上运行包含敏感生产物料的项目。
+
+## 9. 升级查看器
+
+查看器是安装器受管目录。升级前先预览：
+
+```bash
+npx ai-delivery-workflow@latest init . --dry-run
+```
+
+如果目标项目中的 `.workflow/tools/viewer/` 与新版不同，默认会停止并报告冲突。确认采用新版后执行：
+
+```bash
+npx ai-delivery-workflow@latest init . --force
+npx ai-delivery-workflow@latest doctor .
+```
+
+`--force` 会先把旧查看器备份到 `.workflow/delivery/runtime/backups/<timestamp>/`。
+查看器是可选工具。直接删除 `.workflow/tools/viewer/` 只会停止浏览功能，不影响状态 CLI、Hook、Checkpoint、恢复、研发和发布；此时 `doctor` 输出 `WARN` 但保持成功退出。再次执行 `init` 会重装查看器且不改写正式工作流状态。
+
+不要直接把业务项目中的查看器修改复制回发行仓库。发行源码的唯一权威位置见[查看器维护指南](VIEWER-MAINTENANCE.zh-CN.md)。
+
+## 10. 常见问题
+
+| 现象 | 处理 |
+| --- | --- |
+| 端口被占用 | 使用 `--port 4180`，或停止原来占用端口的进程。 |
+| 浏览器没有自动打开 | 打开终端输出的 URL，或去掉 `--no-open`。 |
+| 页面没有最新文件 | 点击“刷新”，确认文件已写入 `.workflow/`。 |
+| 项目或迭代名称不正确 | 检查 `.workflow/delivery/project.yaml` 和 `workflow-state.yaml`。 |
+| 物料落在“未分配” | 按规范调整目录，或补充 `node_id`。 |
+| 状态显示“未标记” | 增加受支持的状态字段和值。 |
+| 没有上下游关系 | 使用指向真实文件的 `.workflow/...` 或相对路径引用。 |
+| 文本无法预览 | 检查扩展名、文件大小和 UTF-8 编码。 |
+| `doctor` 报告查看器不完整 | 先执行 `init --dry-run`，确认后用 `init --force` 修复受管副本。 |
+
+## 11. 相关文档
+
+- [完整项目手册](PROJECT-MANUAL.zh-CN.md)
+- [查看器维护指南](VIEWER-MAINTENANCE.zh-CN.md)
+- [逐文件参考](FILE-REFERENCE.zh-CN.md)
+- [全流程审计物料](../audit/README.md)