ai-contract-platform/project-docs/AI合同平台-生产上线加速与开发效率整改方案-2026-09-21.md

# AI 合同平台：生产上线加速与开发效率整改方案

日期：2026-09-21

适用范围：当前多场景完整交付与 RC-05～RC-08 收口
目标：保留 60 个现有资产、14 个 Prompt 模块和 144 个真实评测场景，停止新增首发功能，用最短路径完成受控试点及公众上线准备。

## 一、执行结论

当前推进慢的首要原因不是编码能力不足，也不是单个测试本身太慢，而是以下流程问题叠加：

1. 在源码仍会变化时过早冻结候选、生成计划和执行全量认证，随后任何 P0 修复都会使计划、源码哈希、镜像、SBOM、扫描、模型证据和 UAT 证据失效。
2. 开发、独立审查、全量回归、真实模型、UAT、法务审批和生产基础设施被串成一条链，能够并行的工作被顺序等待。
3. 多个执行者共享同一个可变工作树；一边修改代码，一边生成不可变候选证据，技术上必然互相冲突。
4. 测试缺少清晰层级，小修改反复触发广泛回归；最终门禁自身不断扩张，逐渐成为新的大型子产品。
5. 大量原始运行证据、失败轮次和临时脚本留在源码工作树，显著增加归属审阅、哈希、打包、传输和安全扫描成本。
6. 每个阶段结束后继续增加新的治理和基础设施阶段，缺少“首发范围冻结、完成定义和终止规则”。

最关键的整改原则是：**先完成全部变更，再冻结唯一候选；冻结后只允许修复经证据确认的 P0 上线阻断；正式认证只对同一候选执行一次。**

本轮不再发明新的 P1/RC 阶段。后续只围绕 RC-05～RC-08 的既定退出条件执行，直至形成明确的内部受控试点或公众上线 Go/No-Go。

## 二、效率问题的量化证据

以下数据来自当前仓库、历史候选和现有运行证据，不是主观估计。

| 现象 | 当前证据 | 直接影响 |
| --- | --- | --- |
| 候选反复失效 | RC-03 产生 v1～v5；v2 已跑 111/144、v3 已跑 29/144 后均因 P0 作废；磁盘可核实多轮场景运行至少 118.8 分钟，其中至少 49.4 分钟明确因候选失效浪费 | 运行时间、计划、哈希与报告反复重做 |
| 冻结后仍持续修补 | RC-04 在一天内从 `.1` 到 `.10` 产生 10 个 tag，即首次冻结后又修补 9 次 | 每次都可能使镜像、SBOM、安装包和 UAT 证据重新失效 |
| 工作树过重 | 当前有 41 个 tracked 状态项、8,906 个未跟踪文件，未跟踪内容约 719.05 MiB | 归属审阅、Git 状态、复制、压缩及扫描都变慢，且容易误收或漏收 |
| 证据目录膨胀 | 未跟踪文件主要集中于 QA 证据；包含大量 JSON、XML、Markdown 和历史失败轮次 | 源码与运行产物边界不清，候选冻结成本持续上升 |
| 测试重复运行 | 可解析的 133 份顶层 JUnit XML 累计记录 9,083 次测试、约 3.23 小时纯测试时间，不含依赖安装、远程传输与等待 | 修复期大量时间消耗在重复广泛回归上 |
| 真实模型天然耗时 | 已有真实探针 draft 约 178.8 秒、semantic review 约 185.0 秒；当前 RC-05 runner 按场景串行；280 次正式调用按平均值串行约 14.1 小时、2 并发理想下限约 7.1 小时 | 不能放在交互式开发循环中反复执行，只应在不可变候选上后台执行 |
| 自动门禁扩张 | 当前未提交新增代码中，大部分体量集中在评测 runner、ledger、生产预检、发布包和其测试 | “证明系统可发布”的工具本身又需要持续开发、审计和证明 |
| 自动流水线未充分提速 | 仓库已有 `.github/workflows/build-test-quality-gate.yml` 等定义，但主 Python job 仍将 Contract、重复 P0、AI、Worker、SDK、Infra 和迁移串行执行；当前 Gitea 上实际触发与必需检查状态仍需确认 | 自动化入口存在，但串行、重复和运行平台未形成高效闭环 |
| Python 测试热区明显 | 当前 collect-only 共约 3,599 项；已有 1,213 项门禁串行用时约 46.5 分钟，最慢 10 个测试类占约 89.5%，主要时间花在重复初始化 FastAPI、SQLite schema 和身份数据 | 盲目增加机器或全量并发不能解决 fixture 重复初始化问题 |
| Web 测试进程开销 | 既有 192 项测试被拆成约 33 次 Node 子进程时约 30 秒，单进程执行同组测试约 2.69 秒 | 测试逻辑很快，主要时间浪费在重复启动进程 |

> `FREEZE` 归属审阅时的最终冻结前快照为 8,907 个未跟踪文件、约 719.47 MiB。上表的 8,906/719.05 MiB 是本报告文件写入前的即时历史采样，保留原值用于追溯，不再作为候选归属基准；本次证据分离的可恢复清单见 `docs/qa/multiscene-closeout-20260910/freeze-evidence-separation-20260921.md`。

这些证据说明，近百小时并不是都用于有效产品开发；相当一部分耗时来自候选作废、重复认证、环境等待和证据管理。

## 三、首发范围与停止规则

### 3.1 首发范围保持不变

- 保留 60 个现有资产，不收缩为采购单场景。
- 保留 14 个 Prompt 模块。
- 保留 144 个正式评测场景和最多 280 次应用适配器调用预算。
- 保留个人、企业、律师事务所三类目标用户及既有关键业务旅程。
- 保留身份/租户隔离、事实完整性、备份恢复、迁移兼容、TLS/密钥、模型失败与人工接管等底线门禁。

### 3.2 从现在起禁止进入本次首发的工作

- 新模板批次、新模型供应商、新云基础设施、新治理看板和非阻断型体验优化。
- 双云 KMS、外部不可变见证、超大关系图等已经明确不阻塞首发的能力。
- 无真实反例支持的“再加一层保险”式自定义证明框架。
- 为每个失败轮次创建正式 Git tag、一次性脚本或独立长报告。
- 因外部账号、证书、政策或主机暂缺而继续编写无关模拟功能。

这些事项进入上线后 backlog，不得修改当前候选。

### 3.3 缺陷分级与硬性停止条件

只有以下问题可以打断候选并进入首发修复：

- P0：越权、跨租户泄露、数据丢失/静默覆盖、关键合同事实错误或丢失、正常主旅程不可用、无法安装/恢复/回退、密钥泄漏、公众注册被错误开放。
- P1：有明确业务影响且没有安全替代路径的发布阻断。是否纳入必须由发布负责人一次性裁定。
- P2/P3：样式、重构、额外措辞、性能微调、治理增强和低概率非核心问题，全部进入上线后 backlog。

冻结后发现 P0 时，旧候选立即标记失效；先集中收齐同批 P0，以只重新冻结一次为效率目标。若随后再次发现实证 P0 或获批 P1，必须继续保持 `NO_GO`、作废候选并由发布负责人决定后续，不能为了遵守次数目标带缺陷放行。禁止“修一个、冻结一次、全量跑一次”。

## 四、新的端到端工作方式

### 4.1 三条并行工作流

| 工作流 | 内容 | 是否等待其他流 |
| --- | --- | --- |
| 工程流 | 代码归属、P0 修复、定向测试、唯一候选、镜像和安装包 | 冻结前不等待法务材料；冻结后不再增加功能 |
| 认证/UAT 流 | 确定性回归、真实模型矩阵、发布审批证据、隔离 UAT、备份恢复 | 只消费唯一候选，不在执行期间接受源码变化 |
| 外部准备流 | 政策、同意证据、域名、TLS、Provider、Redis、监控、审批人和切流授权 | 从第 0 天并行准备，不阻塞工程流；缺失时只阻塞公众开放 |

任何外部依赖必须记录为“责任人、缺少材料、最晚提供时间、影响的放行面”，不能被改写为新的开发任务。

### 4.2 独立工作树与单一集成人

- 每个并行实现任务使用独立 Git worktree/分支，禁止多个实现者共同修改发布工作树。
- 每个任务预先声明可修改文件；交叉文件由单一集成人处理。
- 审查者只读审查，不在审查过程中顺手修改候选。
- 集成人完成合并、冲突处理和定向回归后，发布工作树进入只读冻结。
- 计划、source manifest、镜像、SBOM、扫描、安装包、模型矩阵和 UAT 必须绑定同一 commit 与镜像 digest。
- 通过 UAT 的镜像直接晋级；禁止在生产前重新构建“看起来相同”的另一份镜像。

### 4.3 证据与源码分离

- Git 只保留最终摘要、manifest、必要的审计索引和摘要哈希。
- 原始 JSON、JUnit XML、每案例输出、压缩包、镜像与失败诊断统一写入仓库外的持久构建产物目录。
- 每次 CI 运行使用独立 run ID；失败运行保留在产物存储，不创建正式 tag。
- 临时 UAT 主机 `192.168.3.62` 不能成为镜像、数据库备份或证据的唯一保存点。
- 当前约 8,906 个未跟踪文件必须先做归属审阅；未经审阅不得批量删除，也不得整体纳入候选。

## 五、测试与验证提速方案

### 5.1 四层验证模型

| 层级 | 触发时机 | 内容 | 时间目标 |
| --- | --- | --- | --- |
| T0 快速反馈 | 每次小改动 | 语法/类型、格式、直接失败反例、修改文件对应单测；不启动 Docker、不调用真实模型 | ≤ 3 分钟 |
| T1 受影响回归 | 合并一个修复包 | 按路径映射运行受影响服务和契约测试；安全修改补对应攻击反例 | ≤ 10 分钟 |
| T2 候选全量门禁 | 唯一候选冻结后一次 | 全部确定性回归、Linux 安全项、构建、SBOM、扫描、安装包 | ≤ 30～45 分钟，不含镜像首次拉取 |
| T3 真实认证与 UAT | T2 全绿后 | 144 场景真实模型、发布证据、同镜像 UAT、恢复和回退 | 后台运行；不占用交互开发任务 |

最终切流前允许再做一次只读生产预检，但不得借此重新执行整个开发期测试集。

### 5.2 平台分工

- Windows 负责开发期快速单元/集成测试和前端测试。
- Linux 从一开始负责符号链接、权限、owner/mode、容器和其他平台相关安全测试；不再在 Windows 上反复运行已知会跳过的用例。
- 不直接盲目使用 `pytest -n auto`。先验证测试隔离，再按独立测试族或服务拆分 CI job；共享数据库、端口、全局临时目录和证据根必须各 job 隔离。
- 普通修复期默认只跑失败反例和受影响套件；安全、迁移、共享契约和其他高风险修改按风险扩大验证。独立审查安排在修改完成后一次进行，全量套件安排在审查意见合并后一次进行。

### 5.3 已确认的测试热区优化

- 将 Contract、AI、Infra/SDK/Worker、迁移和 Web 拆为并行 CI jobs，不再在一个 Python job 内顺序等待。
- P0 41 项只作为最先失败的 smoke job 执行一次；完整套件若已覆盖这些用例，不在同一流水线重复执行。
- Python 并行先用 4 worker 连续验证三轮稳定性，再设为默认；出现共享数据库、端口或临时目录冲突时先隔离 fixture，不以随机重跑掩盖问题。
- 优先优化 `test_multiscene_base_journeys` 等最慢测试：每 worker 预建 SQLite schema 模板并复制，或使用事务/savepoint 回滚；迁移/schema 正确性继续由独立测试验证。
- Web 的 37 个测试文件改为一次 Node test runner 调用，避免约 33 次子进程启动；保留一次显式 typecheck，避免在同一门禁中又由 build 重复完成等价检查。
- 每次 CI 上传 JUnit 和最慢 50 项耗时；没有耗时基线的“并行优化”不得直接进入发布门禁。
- 对同一分支启用并发组和取消旧 run，防止过时提交继续消耗执行资源。
- 加固的 Linux release builder 保持确定性串行语义；提速方式是冻结后只构建一次，不在当前阶段冒险并行化四镜像构建。

### 5.4 现有 CI 的最小提速落地

当前候选冻结前不临时加入大量 CI 重构。冻结完成后在独立分支改造现有 workflow，并确认 Gitea runner 的触发、缓存、必需检查和产物保留均真实可用：

1. `quick`：路径变更识别、语法/格式、定向单测，目标 3 分钟。
2. `affected`：后端、AI、前端、发布工具按目录并行，目标 10 分钟。
3. `linux-security`：符号链接、权限、TLS、Compose 和安装器安全用例。
4. `candidate`：只允许在候选标签前运行一次，生成 manifest、镜像、SBOM、扫描和安装/回退包。
5. `model-eval`：手动批准后对冻结 SHA 后台运行，最多 2 并发，保存进度、失败原因和最终摘要。
6. `uat`：只接收上一阶段镜像 digest，执行部署、健康检查、迁移、关键旅程、备份恢复与回退。

所有 job 使用统一入口和固定依赖；不得由不同人员复制命令后手工拼装“等价证据”。

### 5.5 真实模型止损规则

- 开发期只允许少量代表探针，不执行完整矩阵。
- 正式 144 场景只能对不可变 commit、Prompt、资产、schema 和 runner 执行一次。
- 当前 runner 仍是串行。若原生 `max_workers=2` 能在半个工作日内完成，并证明单一 ledger/summary、原子 claim、停止派发和 resume 语义三轮稳定，则纳入冻结前最后一个工具修复；禁止用两个外部 runner 分叉证据。
- 若上述并发改造不能在时限内稳定通过，就不为了节省约 7 小时而延误候选冻结，直接使用现有串行 runner 在夜间完成 12～14 小时后台作业。
- 启用并发时固定最多 2 并发，无静默自动重试、无 fallback 冒充成功。
- 先运行矩阵内代表场景；出现同类系统性失败立即暂停该组，修根因，不继续消耗额度。
- 280 次调用按现有实测平均值，2 并发理想下限约 7.1 小时，排期预留 8～12 小时；保持串行则预留 12～14 小时。不再把这段后台等待描述为人工开发耗时。
- 模型作业运行期间，工程人员可并行准备 UAT 和外部材料；不得围绕未完成进度持续轮询和写报告。

## 六、任务组织与沟通提速

### 6.1 一个任务只交付一个可验收结果

不再使用持续近百小时、不断追加“继续下一阶段”的单一任务。后续拆为以下有明确终点的执行任务：

1. `FREEZE`：完成归属审阅、合并、唯一 commit、候选 manifest；最长半天。
2. `BUILD`：生成同一候选的镜像、SBOM、扫描和安装/回退包；最长半天。
3. `RC05-RUN`：执行代表探针及完整真实矩阵；最长一个后台窗口。
4. `RC06-UAT`：完成 74 项发布证据及两工作区、多角色 UAT；最长一个工作日。
5. `RC07-RECOVERY`：完成真实备份、恢复、rollback/forward 与 RPO/RTO；最长半个工作日。
6. `RC08-PRODUCTION`：只收口外部生产材料和切流演练；最长一个工作日，外部等待单独计时。

每个任务完成时只输出：候选 SHA、通过/失败、剩余 blocker、责任人、下一必要动作。禁止自动扩展为新的功能阶段。

### 6.2 固定节奏

- 每个任务开始先做 15 分钟环境预检：网络、磁盘、Docker、数据库、凭据、端口、时间同步和依赖缓存。
- 每天只设置两个状态检查点；中间只在新增 P0、需要用户材料或任务完成时通知。
- 同一阻断连续出现两次后停止重跑，先做根因分析。
- 运行时间和等待时间分开统计：编码/修复、自动测试、真实模型、环境等待、外部审批分别记账。
- 陈钰麒（总经理）是本轮唯一人工发布审核人，拥有范围和 Go/No-Go 决策权；技术门禁自动执行，不再追加第二名发布审核人。

## 七、最快上线排期

前提：从现在起冻结新增功能；现有代码级门禁维持全绿；所需账号、证书、审批人和生产材料能够按时提供。这里的“第 N 天”是有效工程日，不包含外部材料无人提供的等待时间。

| 时间 | 并行执行 | 退出条件 |
| --- | --- | --- |
| 第 0 天，0～4 小时 | 审阅 41 个 tracked 状态项和约 8,906 个未跟踪文件；移出原始证据；保护用户已有 `docs/architecture/local-development.md`、`start-dev.ps1`；合并并冻结唯一 commit/manifest；同时发出外部材料清单 | 无未归属源码；唯一候选 SHA；发布工作树只读 |
| 第 1 天 | A 构建一次镜像/SBOM/扫描/安装包；B 部署 `192.168.3.62`；C 代表模型场景通过后，以已验证的最多 2 并发或现有串行 runner 启动全矩阵；D 并行准备绑定 60 资产＋14 Prompt 精确 hash 的一份批次审批及政策/域名/证书材料 | 构建产物 hash 一致；UAT 健康；代表场景无系统性失败 |
| 第 2 天 | 收口 RC-05；生成 RC-06 批次；执行管理员＋2 名普通成员、2 个工作区的 API/UI UAT | 144 场景都有终态；无未知、静默降级或未解释失败；运行时快照一致 |
| 第 3 天 | 完成 RC-06；用同一候选执行真实备份、恢复、rollback/forward、RPO/RTO 和单一具名审核人签名 | 数据和 hash 核验通过；可作出内部受控试点 Go/No-Go |
| 第 4～5 天 | 收口真实 Provider、正式域名/TLS、双 Redis、密钥、监控告警、正式政策和切流/回退演练 | RC-08 公众 blocker 为 0；发布负责人明确授权公众切流 |

若外部材料尚未齐全，工程侧仍以第 3 天形成完整多场景内部受控试点候选为目标，继续关闭公众注册并维持公众开放 `NO_GO`。这不是缩减产品场景，只是把代码完成与外部放行分开判断。

## 八、人员与 AI 的责任边界

AI 可以：

- 完成代码分析、P0 修复、测试、证据整理、差异说明、审阅包生成和自动质量判断。
- 预填审批材料、识别缺失项、运行隔离 UAT、监控长任务并在失败时给出根因。
- 在明确授权的测试环境执行可恢复的安装、迁移和回退演练。

AI 不能冒充完成：

- 具名法务人员的正式政策签署或法律结论。
- 唯一具名审核人陈钰麒的身份、私钥或签名；AI 只能预填材料和自动核验，不能冒签。
- 真实生产 Provider、域名、证书、密钥和告警接收人的提供。
- 风险接受、破坏性生产回退批准和最终公众切流授权。

这些外部批准不齐时，系统可以完成开发并进入白名单内部试点，但不能被描述为已经获得公众生产正式批准。

本轮恢复和回退采用“一个人、一次人工决定、一个运营签名”的口径。公开政策也只由陈钰麒一人负责；法律文本签名与公钥信任确认仍使用两把用途隔离密钥形成两条技术签名，但不再要求第二名审核人，材料生成与验签由系统自动完成。离线恢复根密钥只用于签发、轮换或吊销恢复 keyring，日常恢复审批密钥只用于具体证据；两者必须为不同 Ed25519 公钥。两个普通成员账号和两个工作区属于自动化 UAT 覆盖，不是额外审核人。企业租户可配置的业务审批、特权身份操作等产品能力不在本次发布审核简化范围内。

## 九、效率指标与上线看板

从下一任务开始只跟踪以下指标：

| 指标 | 目标 |
| --- | --- |
| T0 快速反馈 | 中位数 ≤ 3 分钟 |
| T1 受影响回归 | ≤ 10 分钟 |
| T2 确定性候选门禁 | ≤ 30～45 分钟 |
| 候选冻结后的重新冻结次数 | 目标 0，通常最多 1；新的实证阻断始终优先 |
| 每个 RC 的完整回归次数 | 1 次；最终切流只做只读复探 |
| 原始生成产物进入源码工作树 | 0 |
| 代码审查到全绿 | ≤ 4 小时 |
| 真实模型矩阵 | 只对唯一候选执行 1 次 |
| 外部等待 | 单独显示，不计入工程开发耗时 |
| 新增非阻断首发功能 | 0 |

测试热区和 CI 并行改造稳定后，再把 PR 确定性门禁目标收紧至 10～18 分钟；SQLite fixture 复用验证稳定后，相关 1,213 项 Python 门禁的目标墙钟为约 6～12 分钟。上述是改造目标，必须用三轮实际结果校准后才能作为承诺。

滚动看板只保留六列：`工作包`、`唯一候选 SHA`、`当前状态`、`唯一 blocker`、`责任人`、`预计解除时间`。不再维护彼此重叠的阶段性长报告。

## 十、立即执行的唯一下一步

下一步不是继续开发新能力，而是执行 `FREEZE`：

1. 审阅当前 41 个 tracked 状态项和约 8,906 个未跟踪文件的归属。
2. 保留并隔离用户已有的 `docs/architecture/local-development.md`、`start-dev.ps1` 修改。
3. 将原始运行产物移出发布工作树，只保留最终摘要、索引和 hash；不未经审阅批量删除。
4. 对 RC-05～RC-08 代码完成一次最终只读审查和受影响回归。
5. 合并为唯一 commit，生成唯一 source manifest；门禁通过后再创建一个候选 tag。
6. 冻结后立即并行启动 BUILD、UAT 环境部署、代表模型探针和外部材料准备。

在 `FREEZE` 完成前，不应启动 144 场景真实矩阵、重新构建正式镜像或生成新的发布证明；否则仍会重复当前的作废循环。

## 十一、当前放行判断

- 代码级 RC-05～RC-08 门禁：已具备冻结准备条件。
- 唯一不可变候选：尚未形成。
- 完整多场景内部受控试点：当前仍为 `NO_GO`，目标在唯一候选形成后 3 个有效工程日内作出真实 Go/No-Go。
- 公众开放：当前仍为 `NO_GO`；只有正式政策、真实生产基础设施、最终审批和切流演练全部完成后才能改变。

本方案的提速来自减少返工、并行处理等待和只认证一次，不来自取消安全、质量或合规底线。