---
title: "文档修改、版本差异与智能体变更说明能力缺口分析"
status: done
created: 2026-09-13
updated: 2026-09-13
severity: high
---

# 文档修改、版本差异与智能体变更说明能力缺口分析

## 1. 结论

系统已有受控文档生命周期、编辑租约、正文 SHA-256、审计日志、智能体变更提案、自由文档版本表和阶段通知 Outbox，可作为本能力的基础；但当前尚不存在可信的“受控文档版本库”。受控正文仍以工作区单个 `output.md` 为事实源，人工或智能体更新会覆盖现状，无法复原任一历史正文，也无法可靠回答“谁在何时基于哪个智能体版本改了什么”。

本需求不能通过前端缓存一份旧正文后做颜色标记来完成。必须把不可变正文快照、以智能体生成为边界的版本周期、每次已提交人工修改、精确 diff、智能体变更报告和负责人通知放入同一个服务端一致性模型。

## 2. 用户规则的确定性解释

用户描述中的“版本以智能体修改为准”按以下语义实现：

1. 模板或一次成功提交的智能体/智能体小队产物，是一个版本周期的 `baseline`。
2. 此后所有人工保存都形成该版本下的 `revision`，改变当前 `head`，但不增加面向用户的版本号。
3. 下次智能体基于当时的 `head` 生成成功后，旧版本以该 `head` 封存；智能体输出成为新版本的 `baseline`。
4. “人工修改标记”永远计算为当前版本 `baseline → head`。智能体新版本生效后该标记归零，后续只显示相对新 baseline 的人工修改。
5. 两个版本的默认比较使用各版本的最终内容：已封存版本取 `sealed_head`，当前开放版本取实时 `head`；智能体自身的改动单独用“上一版本最终内容 → 新版本 baseline”表达。

该解释既满足“模板/上一次智能体生成 + 下一次智能体生成前人工修改为一个版本”，也不会把每次自动保存误展示成一个正式版本。

## 3. 已确认的现有基础

| 能力 | 当前证据 | 可复用部分 |
|---|---|---|
| 受控文档元数据 | `deploy/postgres/goose/00001_baseline.sql:230-280` | `document_records`、三权、状态、当前 SHA、版本号 |
| 编辑互斥 | `internal/docgov/lease.go:41-180` | human/squad 租约、心跳和忙状态 |
| 人工保存入口 | `internal/docgov/lease.go:290-360` | 编制人/状态校验与 `expected_sha256` 乐观锁 |
| 智能体修改授权 | `internal/docgov/engine.go:448-577`、`internal/bizdev/service.go:451-538` | 已认领文档先提案、编制人裁决 |
| 智能体执行归属 | `internal/squad/models.go:35-95,216-226` | 小队角色、步骤、manifest 与工作区信息 |
| 自由文档版本 | `internal/freedoc/service.go:416-535` | 事务、`FOR UPDATE`、每次保存快照与 If-Match |
| 文档血缘 | `deploy/postgres/goose/00010_2026-09-11-project-workflows-and-lineage.sql:66-84` | 上下游文档版本、哈希和 stale 传播 |
| 可靠通知基础 | `deploy/postgres/goose/00018_2026-09-12-outbox-notifications-stage-advance.sql`、`internal/notification/service.go` | Outbox、用户通知、去重键 |
| 右侧块编辑器 | `web/src/components/doc/BlockRenderer.tsx`、`BlockEditorModal.tsx` | 块级阅读、编辑、批注和右侧栏布局 |

## 4. 已确认缺口

| ID | 缺口 | 当前证据 | 后果 |
|---|---|---|---|
| DOCREV-01 | 受控正文没有不可变历史快照 | `ReadDocumentContent` 只读取当前工作区 `output.md`；`document_records.version` 没有对应的受控版本表 | 不能查看旧版本、恢复证据或验证历史哈希 |
| DOCREV-02 | 人工保存只覆盖文件和当前哈希 | `SaveDocumentContent` 写 `output.md` 后更新 `document_records`，不增加版本/修订记录；数据库错误还被忽略 | 无法记录具体修改人和前后正文；文件与 DB 可分裂 |
| DOCREV-03 | 前端块编辑尚未持久化 | `handleSaveBlockEdit` 只修改 React `docCache`；`saveDocumentContent` 没有调用者；编辑弹窗把修改人硬编码为“张工” | 刷新丢失、归属不可信、展示与服务端不一致 |
| DOCREV-04 | 智能体完成只更新当前哈希 | `internal/bizdev/service.go:694-705` 只调用 `SetDocumentWorkDir` 和 `MarkDocumentContentUpdated` | 不能把 run、输入快照、输出快照和版本关联 |
| DOCREV-05 | 现有提案不是实际 diff | `service.go:499-502` 在智能体执行前写入通用文案，未绑定真实 before/after | 不能作为生成完成后的改动摘要、风险或影响证据 |
| DOCREV-06 | 块锚点不稳定 | `markdownToBlockAST` 每次解析使用随机 `blk_*` ID | 刷新或换版本后不能稳定定位修改块、批注和 diff |
| DOCREV-07 | 自由文档“每次保存一个版本”与本需求语义不同 | `freedoc.UpdateDocument` 每次正文变化都 `current_version_id + 1` | 同一右侧栏内“版本”概念不一致，自动保存会制造版本噪声 |
| DOCREV-08 | 通知只覆盖阶段推进 | `notification/types.go` 只有 stage-ready 类型；前端仅 `StageAdvanceBanner` 消费 | 文档负责人不会收到智能体版本摘要、风险和影响 |
| DOCREV-09 | 内容修改链路的一致性和授权边界不足以支撑审计 | 租约 API 接受客户端 holder type/id；部分 DocGov 入口只认证后直接调用领域引擎；当前锁主要是进程内 mutex | 多实例、伪造 holder、并发提交时可能发生越权或静默覆盖 |

## 5. 根因分析

### 5.1 “当前文档”同时承担事实源、工作副本和历史版本

`document_records` 的 `version` 和 `content_sha256` 只是当前指针；`output.md` 同时被智能体工作区、人工编辑和读取 API 使用。缺少 immutable snapshot 后，审计日志只能证明发生过一个动作，不能证明动作前后内容。

### 5.2 版本、修订、生命周期三种概念没有拆开

- 智能体生成版本：本需求要求的业务版本边界；
- 人工保存修订：高频、可聚合展示，但必须逐次留痕；
- 送审/批准快照：生命周期冻结点。

当前单个 `version` 整数无法同时表达三者，继续叠加字段会导致比较对象含糊。

### 5.3 UI 的 Block AST 是临时视图，不是稳定编辑协议

Markdown 每次解析都会重新生成随机块 ID；编辑 metadata 由浏览器填写，既不能作为服务端身份，也无法跨快照追踪。需要由服务端产生稳定 block map，并由 immutable snapshot 保存。

### 5.4 智能体说明与确定性事实没有分层

智能体适合解释“为什么改、有哪些风险”，但真实增删内容必须由服务端 diff 得出，上下游影响必须由工作流/血缘图计算，风险等级也不能允许模型自行降级。当前变更提案把三者都存为自由文本，且没有版本关联。

## 6. 严重度

`high`

该能力尚未对外承诺为已实现，因此不是现有数据破坏事件；但若仅增加 UI 高亮便宣称完成，会形成错误审计证据，并在多人/多智能体协作下引入静默覆盖、错误归属和不完整通知。

## 7. 设计边界

- 受控工作流文档与自由文档继续使用各自权限/生命周期策略；只共享底层快照、修订和 diff 能力。
- Markdown 正文为规范化内容真源，Block AST 是带稳定映射的编辑/展示投影，避免双真源。
- 未保存的浏览器按键不属于审计记录；每次服务端成功提交才是 revision。
- 批注、审核意见与正文修改是不同事件，不混入人工正文高亮。
- 已批准内容不可原地修改；后续修改必须经受控变更/驳回回编制流程创建新工作周期。

## 8. 关联整改

- System design: [../system-design/document-revision-management.md](../system-design/document-revision-management.md)
- Remediation: [../remediation/2026-09-13-document-revision-management-implementation-plan.md](../remediation/2026-09-13-document-revision-management-implementation-plan.md)
- Short-term: [../ops/short-term/2026-09-13-document-revision-management-design.md](../archive/ops/2026-09-13-document-revision-management-design.md)

## 9. 开放问题

方案给出推荐默认值，等待评审时确认：

1. 高/严重风险的智能体候选是否一律要求编制负责人再次确认后才成为新版本（推荐：是）。
2. 首期是否同时迁移自由文档到“智能体版本 + 人工修订”语义（推荐：底层统一，UI 第二波启用）。
3. 历史快照默认保留期限（推荐：受控文档随项目/法规保留策略；自由文档默认 365 天且可配置，不做静默硬删除）。