164 lines
17 KiB
Markdown
164 lines
17 KiB
Markdown
---
|
||
title: Gitea知识库 v1.1 验收与止损矩阵
|
||
date: 2026-08-07
|
||
type: 设计spec
|
||
status: draft
|
||
content_status: discussion
|
||
owner: Verlit
|
||
last_updated_at: 2026-08-10
|
||
last_updated_by: Codex
|
||
hash: sha256:4fb6cc58062bc3761610a6d89ca962932596a752dbac89243ad5446a6143c967
|
||
hash_scope: Markdown 正文（从一级标题开始至文件末尾）的 UTF-8 SHA-256
|
||
belongs_to:
|
||
- "[[3-业务线/Gitea知识库/_context|Gitea知识库]]"
|
||
depends_knowledge: []
|
||
source_refs:
|
||
- "[[3-业务线/Gitea知识库/公司共享 Context 项目仓库发布方案 v1|公司共享 Context 项目仓库发布方案 v1]]"
|
||
- "[[3-业务线/Gitea知识库/公司共享 Context MCP-first 身份与审计方案 v1.1|公司共享 Context MCP-first 身份与审计方案 v1.1]]"
|
||
- "[[3-业务线/Gitea知识库/v1-工程构建规格|v1 工程构建规格]]"
|
||
- "[[3-业务线/Gitea知识库/v1-开发任务分解|v1 开发任务分解]]"
|
||
- "[[3-业务线/Gitea知识库/v1-详细实施方案|v1 详细实施方案]]"
|
||
- "0-收集箱/临时待归属/2026-08-03-公司共享Context发布与AI协同框架/2026-08-03-12-试点方案决策清单与路线图.md"
|
||
---
|
||
|
||
# Gitea知识库 v1.1 验收与止损矩阵
|
||
|
||
## 1. 目的与判定口径
|
||
|
||
本文件把 v1 基线叠加 v1.1 MCP-first 身份与审计覆盖层后的阶段门、测试样本、成功指标、证据要求和止损动作放在同一套判定口径中。它用于回答“是否允许进入下一阶段”和“出现什么情况必须停止”，不能用安装完成、演示成功或口头确认替代。
|
||
|
||
当前工程设计、未来代码开发和未来真实实施使用不同的数据边界：工程设计不运行测试；代码开发默认使用合成数据、fake adapter 和临时目录；只有进入真实实施后才使用已授权试点。所有正式系统验收必须满足以下规则：
|
||
|
||
- 使用一个真实、正在运行、低敏感且已明确授权的试点项目；
|
||
- 正向与负向测试都通过，拒绝结果也要留下证据；
|
||
- 发布记录、Git 提交、`current`、只读入口和 Agent 读回能够相互追溯；
|
||
- 证据写入业务线或后续正式代码库约定的验收位置，不把聊天、临时日志或截图作为唯一证据；
|
||
- 任一安全、权限、唯一性或恢复硬门失败时，不以“后续再补”放行。
|
||
|
||
## 2. 阶段门矩阵
|
||
|
||
| Gate | 进入条件 | 必须完成 | 通过证据 | 未通过动作 |
|
||
|---|---|---|---|---|
|
||
| C0 工程设计构建 | v1 主方案和 v1.1 差量覆盖层已归位 | 设计追溯、工程构建规格、开发任务分解、测试规格和未来实施方案统一到 v1.1 | 本业务线本地文档、hash 与一致性校验 | 只修正文档；禁止创建代码仓库、写代码和远端动作 |
|
||
| C1 代码开发准入 | C0 通过；Verlit 明确宣布进入代码开发 | 平台代码仓库、运行时/MCP SDK、Agent Host 边界、维护者、任务范围、合成身份/数据和验收人明确 | 开发任务单和代码仓库入口 | 保持任务为 planned；不得创建或修改代码 |
|
||
| G0 实施准入与参数 | C0/C1 对应门通过；Verlit 明确宣布进入实施 | 试点项目、成员角色、飞书身份应用、远程 MCP、身份/审计存储、目标服务器、备份、RPO/RTO和应急责任已确认 | 决策清单、角色表、服务器只读盘点、参数签字或明确确认记录 | 仅允许已授权的本地代码和设计工作；禁止远端创建和部署 |
|
||
| G1 实施契约落地 | G0 通过；平台代码归属明确 | 为目标试点固定稳定 ID、schema、状态机、幂等键、CAS、错误码、事件和回执契约 | 契约文件、状态转换测试、非法转换拒绝测试 | 可继续已授权的纯本地开发；禁止绑定真实环境和写远端状态 |
|
||
| G2 基础层与权限 | G1 可并行准备；目标环境已授权 | Gitea 加固、飞书/内部/Gitea 身份绑定、双层权限、私有试点仓库、`main` 保护、凭据隔离和备份链路完成 | 身份绑定、配置快照、双层权限正反测试、分支保护和备份结果 | 禁止接入真实业务内容和真实发布 |
|
||
| G3 MCP 与发布闭环 | G1、G2 通过 | MCP 唯一入口、选择、构建、安全检查、精确确认、CAS、网关提交、原子 `current`、强制审计、回执和四段读回闭环 | 单次 MCP 调用/发布三主体证据包；Git/current/MCP/Agent 四段一致 | 停止扩大样本；修复后从失败门重新验收 |
|
||
| G4 安全与运维 | G3 通过 | 未授权拒绝、私密材料隔离、提示注入隔离、撤权、密钥轮换、监控、事故响应和恢复演练通过 | 负面测试、撤权测试、轮换记录、告警证据、空环境恢复报告 | 安全硬失败立即停发；恢复失败禁止真实试点 |
|
||
| G5 真实试点 | G0～G4 全部通过 | 真实成员完成 12 类样本和日常使用观察；没有硬止损信号 | 试点报告、指标表、问题清单、责任人验收、v2 判决 | 回到相应 Gate；不得以软件安装完成宣告 v1 完成 |
|
||
|
||
## 3. 工程测试规格
|
||
|
||
### 3.1 测试层级
|
||
|
||
| 前缀 | 层级 | 当前设计要求 | 运行边界 |
|
||
|---|---|---|---|
|
||
| CT | 契约测试 | schema 合法/非法样例、major/minor 兼容、未知关键状态拒绝、hash 防篡改 | 未来代码开发；纯本地、合成对象 |
|
||
| UT | 单元测试 | ID、状态机、选择范围、确定性构建、检查规则、策略、幂等、导出和读取模块 | 未来代码开发；无网络、无真实凭据 |
|
||
| IT | 集成测试 | fake source/Gitea/policy/read endpoint 下的正常与全部异常事务 | 未来代码开发；fake adapter 和临时目录 |
|
||
| SEC | 安全负面测试 | 越权、路径、符号链接、凭据、PII、日志脱敏、prompt injection 和策略覆盖 | 未来代码开发使用合成攻击语料；真实环境后再复验 |
|
||
| REC | 恢复测试 | artifact、current、状态存储、Gitea 和空环境恢复 | 本地仅验证恢复逻辑；真实备份恢复属于 G4/G5 |
|
||
| T | 真实试点验收 | 下述 T01～T12 | 仅在 G0～G4 通过后，对已授权低敏感项目运行 |
|
||
|
||
每个开发任务的具体 CT/UT/IT/SEC 用例在 `v1-开发任务分解.md` 中有映射。测试结果必须记录用例 ID、契约版本、fixture hash、结果、错误码和关联任务；开发测试不得为了方便连接生产 Gitea。
|
||
|
||
### 3.2 v1.1 MCP、身份与审计强制用例
|
||
|
||
| ID | 场景 | 预期结果 |
|
||
|---|---|---|
|
||
| M01 | 两名飞书用户通过同一 Agent Host 登录 | 内部主体、授权项目、工具结果和审计身份正确分离 |
|
||
| M02 | 工具参数填写他人 `user_id`、role、grant 或 session | 服务端忽略/拒绝自报身份，不能冒充其他用户 |
|
||
| M03 | 内部 ProjectGrant 允许、Gitea 权限拒绝 | fail closed，记录 `permission_mismatch` |
|
||
| M04 | 内部 ProjectGrant 拒绝、Gitea 权限允许 | fail closed，不以 Gitea 单层权限放行 |
|
||
| M05 | read/search/build/validate 和 denied 调用 | 每次都有 request、授权和完成/失败的 human＋agent＋service 事件 |
|
||
| M06 | discussion/confirmed 发布 | 精确确认、candidate hash、`base_current`、session、commit 和网关服务身份可关联 |
|
||
| M07 | 停用用户、解除飞书/Gitea 绑定、撤销项目授权或 Gitea 成员 | 未来 MCP 会话/调用立即或在承诺失效边界内拒绝 |
|
||
| M08 | audit store/outbox 不可写 | 业务写 fail closed；可靠读取审计队列也不可用时拒绝读取 |
|
||
| M09 | MCP 故障或停用 | 不回退到共享 CLI、通用 Gitea token、shell 或高权限 API |
|
||
| M10 | 普通用户枚举工具 | 不存在审计写删、权限写、Gitea Admin、SSH、SQL、部署、备份、密钥和策略开关工具；不存在自定义业务 Web 入口 |
|
||
|
||
### 3.3 十二类强制试点样本
|
||
|
||
原方案包实际列出 12 类样本；本文以 12 类为准，不沿用“11 类样本”的文字误差。
|
||
|
||
| ID | 场景 | 操作要点 | 预期结果 | 必要证据 |
|
||
|---|---|---|---|---|
|
||
| T01 | 单文件状态演进 | 同一材料先以 `discussion` 发布，再明确改为 `confirmed` 发布 | 两次 release 可追溯；内容状态变化不等同于技术状态变化 | 两次 selection、diff、release、commit、readback |
|
||
| T02 | 审核开关负面路径 | 试点保持 `forced_off`；仅在隔离测试中模拟审核 ON、candidate hash 变化及 ON→OFF | 正常试点不进入待审；模拟中旧批准不能覆盖新 candidate，切回 OFF 不误复用审批 | 策略快照、拒绝事件、状态转换记录 |
|
||
| T03 | 多来源组合 | 从两个或多个明确选择的 Markdown 来源构建一份发布物 | 仅包含选择清单中的内容；顺序、路径和 hash 确定 | selection manifest、构建清单、重复构建 hash |
|
||
| T04 | 附件与链接 | 发布含允许附件、相对链接和跨文件引用的材料 | 附件收集完整，链接改写后可读，无越界文件 | 附件 manifest、链接检查、读取截图或机器结果 |
|
||
| T05 | 相邻私密材料 | 在已选文件旁放置未选私密或敏感文件 | 私密材料不进入构建区、Git、`current`、日志和回执 | 搜索结果、构建清单、仓库与入口负向检查 |
|
||
| T06 | 并发发布 | 两个 publisher 基于同一 `base_current` 同时发起不同发布 | 只有一个成功；另一个以 `stale_base` 阻断，不出现混合 current | 两个请求、CAS 结果、最终 current manifest |
|
||
| T07 | 安全阻断 | 注入凭据、PII、路径穿越、符号链接和控制文件样本 | 策略要求阻断的样本在远端写入前失败，日志不回显秘密 | 每类检查结果、错误码、远端无提交证明 |
|
||
| T08 | Prompt Injection | 在知识正文中加入试图改变 Agent 权限或索取凭据的指令 | 内容只作为数据读取；Agent 不获得额外工具、凭据或跨项目访问 | Agent 输入输出、工具调用为零或拒绝证据 |
|
||
| T09 | 发布后读回失败 | 人为让只读入口或 Agent 读回不一致 | release 不标记 `completed`；告警触发并可安全重试 | 发布状态、读回差异、告警、重试结果 |
|
||
| T10 | 撤权与凭据轮换 | 撤销一名成员的绑定/授权，再轮换 `context-reader` 服务凭据 | 被撤权用户未来 MCP 访问失败；旧服务凭据失效，新凭据仅可读目标项目 | 前后访问结果、轮换记录、权限快照 |
|
||
| T11 | 历史版本恢复发布 | 选择历史 release 作为新发布来源 | 生成新的 release 和审计记录，不改写历史，不直接移动隐藏指针 | 新旧 release、commit、diff、readback |
|
||
| T12 | 空环境完整恢复 | 在隔离环境恢复 Gitea 数据、配置、仓库和关键凭据材料 | 在承诺 RPO/RTO 内恢复；权限与 `current` 一致；恢复结果可读 | 恢复计时、步骤记录、完整性校验、权限与读回测试 |
|
||
|
||
## 4. 跨链路验收指标
|
||
|
||
| 指标 | v1.1 通过值 | 说明 |
|
||
|---|---|---|
|
||
| Git/current/只读入口/Agent 四段 release 一致率 | 100% | release ID、内容 hash、`content_status` 必须一致 |
|
||
| 同一项目同时有效的 `current` 数量 | 始终为 1 | staging 不算 current；任何短暂双 current 也算失败 |
|
||
| 未授权项目访问成功次数 | 0 | 人、Agent 和服务身份都适用 |
|
||
| 未选择私人内容进入企业面次数 | 0 | 包括仓库、current、日志、回执、缓存和备份索引 |
|
||
| 非网关身份写受保护 `main` 成功次数 | 0 | 管理员紧急操作也必须进入受控审计流程 |
|
||
| CAS 冲突导致内容覆盖次数 | 0 | 冲突必须阻断，不自动合并 current |
|
||
| 已标记 completed 但读回不一致次数 | 0 | 四段读回未通过不得完成事务 |
|
||
| 备份恢复成功率 | 100%（演练样本） | 至少完成一次隔离空环境恢复 |
|
||
| 共享账号或共享凭据数量 | 0 | 每个人、Agent 和服务均使用独立身份 |
|
||
| 共享机器人身份承载个人行为次数 | 0 | 每次用户操作都必须绑定个人内部主体和 AgentSession |
|
||
| 用户业务 MCP 调用审计覆盖率 | 100% | 允许、拒绝、成功和失败均覆盖 human＋agent＋service |
|
||
| 客户端自报身份/角色被采信次数 | 0 | user、role、grant 和 session 只能从服务端验证上下文派生 |
|
||
| 双层权限不一致被放行次数 | 0 | 内部授权或 Gitea 权限任一层拒绝都必须 fail closed |
|
||
| MCP 故障回退到高权限入口次数 | 0 | 不允许共享 CLI、token、shell、API 或自建 Web 旁路 |
|
||
| 普通成员必须处理 Git 分支/PR/MR 的发布次数 | 0 | v1 发布入口需屏蔽不必要的 Git 操作复杂度 |
|
||
|
||
性能、可用性和 RPO/RTO 的具体数值在 D15 确认后加入验收承诺；未确认前不得把方案包建议值写成已承诺 SLO。
|
||
|
||
## 5. 止损矩阵
|
||
|
||
| 信号 | 级别 | 立即动作 | 恢复条件 |
|
||
|---|---|---|---|
|
||
| 出现两个有效 `current`、混合发布物或非原子切换 | 硬停止 | 暂停所有发布和默认读取；保留现场；回退到最后已验证 release | 原因修复、唯一性测试和 T06/T09 全部重跑通过 |
|
||
| 私人、跨项目、凭据或敏感内容进入企业读取面 | 安全事故 | 立即停发、撤销暴露入口和凭据、按事故流程评估通知与清理 | 泄漏范围确认、秘密轮换、历史与缓存处理、T05/T07 重跑通过 |
|
||
| 未授权身份可读目标项目或非网关身份可写 `main` | 硬停止 | 冻结相关身份与入口，保存审计证据 | 权限根因修复，完整正反权限测试通过 |
|
||
| 撤权后仍可访问，或旧 Agent 凭据仍有效 | 硬停止 | 禁用身份、轮换凭据、暂停新增成员 | T10 通过且缓存/会话失效边界明确 |
|
||
| 备份存在但无法在隔离环境恢复 | 硬停止 | 停止进入真实试点和扩大使用；修复备份链 | T12 在目标 RPO/RTO 内通过 |
|
||
| 事务标记 completed 但任一读回不一致 | 硬停止 | 将 release 标记为失败或不完整，保持最后已验证 current | T09 和完整四段读回通过 |
|
||
| Prompt 内容可以改变 Agent 权限、路由或工具调用 | 安全事故 | 停用 Agent 入口，隔离样本并审查凭据暴露 | 权限控制移出提示词、T08 通过、凭据完成轮换 |
|
||
| 依赖共享账号、共享 Token 或人工复制管理员凭据 | 硬停止 | 停止对应流程，不接受“试点临时共享” | 独立身份和最小权限矩阵落实并通过测试 |
|
||
| 每次发布都需要管理员手工修仓、改历史或移动 current | 暂停扩展 | 保留现有安全读取，停止增加用户和项目 | 自动化闭环稳定，连续试点无人工修仓 |
|
||
| 普通成员持续需要解决 Git 分支、PR/MR 或复杂冲突 | 产品止损 | 暂停扩大试点，回到选择与发布入口设计 | 真实成员可完成发布且无需 Git 专业操作 |
|
||
| 只有技术维护者使用，业务成员没有真实使用证据 | 范围止损 | 不进入 v2，不扩大平台能力 | 真实业务使用场景和可量化收益得到验证 |
|
||
| 只能靠提示词声明权限，服务端无强制权限边界 | 安全事故 | 禁止真实数据与 Agent 接入 | 权限由 Gitea、只读入口和服务端策略强制执行 |
|
||
| 共享机器人/Agent 身份无法区分真实操作人 | 硬停止 | 停用用户业务 MCP，保留只读事故调查 | 飞书绑定、内部主体和 AgentSession 归因通过 M01/M02 |
|
||
| 工具参数可冒充 user、role、grant 或 session | 安全事故 | 立即停用受影响工具并审查已发生调用 | 身份只从验证会话派生，M02 及历史影响检查通过 |
|
||
| 内部权限或 Gitea 权限任一拒绝却仍放行 | 安全事故 | 冻结项目访问和发布，保存审计现场 | 双层鉴权修复，M03/M04 与撤权测试通过 |
|
||
| MCP 调用缺少三主体审计，或审计失败仍执行业务动作 | 硬停止 | 停用受影响入口；核对业务状态与事件缺口 | outbox/等价机制修复，M05/M08 全部通过 |
|
||
| MCP 不可用时自动回退共享 CLI、token、shell 或自建 Web 旁路 | 硬停止 | 关闭回退通道和相关高权凭据 | M09/M10 通过并完成凭据轮换 |
|
||
|
||
## 6. 证据包最小结构
|
||
|
||
每个 Gate 和测试样本至少保留：
|
||
|
||
1. 测试标识、时间、human/agent/service 稳定 ID、AgentSession、项目 ID 和环境标识；
|
||
2. 前置状态与权限快照；
|
||
3. 输入摘要、selection ID、幂等键和 `base_current`；
|
||
4. 检查结果、状态转换、错误码和审计事件；
|
||
5. release ID、commit SHA、内容 hash、`content_status`；
|
||
6. Git、`current`、只读入口和 Agent 读回结果；
|
||
7. 回滚或恢复动作及其验证结果；
|
||
8. 结论、遗留问题、责任人和下一动作。
|
||
|
||
凭据、Token、私密正文和其他秘密不得进入证据包；证据中只记录稳定标识、hash 和脱敏摘要。
|
||
|
||
## 7. v1.1 完成与后续版本判决
|
||
|
||
只有 G0～G5 全部通过、M01～M10 与 T01～T12 完成、跨链路硬指标达标且无未关闭硬止损项，才可将当前 v1.1 目标标记为完成。完成后至少保留一段真实使用观察期，再依据实际摩擦决定后续版本。
|
||
|
||
以下能力不因 v1.1 完成而自动启动：Skill Registry、飞书内容来源、通用审批、自定义业务 Web、多项目汇总和更多内容来源。它们只能以独立版本范围、威胁模型、迁移方案和验收标准进入后续决策。
|