130 lines
11 KiB
Markdown
130 lines
11 KiB
Markdown
---
|
||
title: Gitea知识库 v1/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:9236e755129218a1625125ecf2c6eaaeda81fc42838bebacf4d392ef66f4403a
|
||
hash_scope: Markdown 正文（从一级标题开始至文件末尾）的 UTF-8 SHA-256
|
||
belongs_to:
|
||
- "[[3-业务线/Gitea知识库/_context|Gitea知识库]]"
|
||
source_refs:
|
||
- "3-业务线/Gitea知识库/公司共享 Context 项目仓库发布方案 v1.md"
|
||
- "3-业务线/Gitea知识库/公司共享 Context MCP-first 身份与审计方案 v1.1.md"
|
||
- "0-收集箱/临时待归属/2026-08-03-公司共享Context发布与AI协同框架/"
|
||
---
|
||
|
||
# Gitea知识库 v1/v1.1 设计追溯与版本关系
|
||
|
||
## 1. 目的
|
||
|
||
本文件固定 v1 主方案、v1.1 差量覆盖层、治理补丁、详细设计、执行单和历史审查之间的采用关系。它不创造新的架构，只回答每份材料进入哪个版本、哪些旧描述被覆盖，以及后续实施步骤应回溯到哪里。
|
||
|
||
```text
|
||
v1 冻结发布基线
|
||
+ v1.1 对入口、身份、权限、Agent 写请求和审计的明确覆盖
|
||
= 当前目标设计
|
||
→ PRD（产品/功能/验收）＋Canvas（流程可视化）＋工程/实施执行文档
|
||
```
|
||
|
||
文件名中保留 `v1-` 的执行文档作为稳定路由，不表示其正文仍停留在旧口径；正文标题、来源和 hash 共同声明当前采用 v1.1。
|
||
|
||
## 2. 真源优先级
|
||
|
||
1. `公司共享 Context MCP-first 身份与审计方案 v1.1.md`：只对其明确列出的入口、身份、权限、Agent 和审计事项具有覆盖优先级。
|
||
2. `公司共享 Context 项目仓库发布方案 v1.md`：其余业务目标、仓库、发布事务、current、状态和试点基线真源，正文保持不可变。
|
||
3. `v1审核开关治理模型_deepseek-v4-pro.md`：只覆盖 confirmed release 的审核开关语义，不改变唯一 current 和发布网关；Agent 能力按 v1.1 覆盖。
|
||
4. `公司共享Context发布与AI协同框架/`：接口、权限、安全、运维和执行细节补充。
|
||
5. `v1最终方案一致性校验_codex.md`：证明 v1 材料在 2026-08-03 时的一致性，不证明后续 v1.1 覆盖项。
|
||
6. 其他架构与合规审查：保留问题发现和收敛历史，不覆盖当前版本真源。
|
||
|
||
任何补充材料与 v1/v1.1 当前组合冲突时，默认停止采用冲突部分；只有形成新的业务线版本决策后才能改变当前目标。v1.1 未明确覆盖的事项不得自行推断为改变 v1。
|
||
|
||
`Gitea知识库 v1.1 产品需求文档 PRD.md` 和 `Gitea知识库 v1.1 完整流程闭环.canvas` 是当前组合设计的派生消费视图：前者承载完整需求、S00～S28、默认值和 Gate，后者承载同一流程的可视化。它们不能反向覆盖 v1/v1.1；发现冲突时必须回到上游版本决策修正。
|
||
|
||
## 3. 详细设计文档分类
|
||
|
||
| 文档 | 分类 | v1 采用结论 | 需要修正或限定的旧描述 |
|
||
|---|---|---|---|
|
||
| 00 项目入口与文档地图 | adopted-with-notes | 采用文档地图、冻结原则和阅读顺序 | “临时归属、不是正式业务线真源”已失效；正式业务线现为 `Gitea知识库` |
|
||
| 01 总体架构与模块边界 | adopted | 四个平面、独立模块和契约连接全部采用 | “需要用户设计”的事项只能补实现参数，不能重开一项目一仓、唯一 current 等冻结决定 |
|
||
| 02 分阶段实施计划与验收门 | adopted | 阶段和验收门采用 | 业务归属与 C0 工程设计已完成；试点与环境参数留到未来 G0，不是当前待办 |
|
||
| 03 来源接入选择与内容构建 | adopted-with-scope | 本地 Markdown 选择、构建、附件和链接规则采用 | v1.1 只使用飞书身份；飞书内容来源仍不进入当前目标 |
|
||
| 04 发布事务版本存储与只读分发 | adopted | 状态机、CAS、幂等、原子导出、恢复和读回采用 | 事务编排技术选型仍待实现阶段决定 |
|
||
| 05 MCP 工具路由与外部系统连接 | adopted-v1.1 | MCP 工具门禁、服务端复核和无高权回退采用 | “MCP 可选、HTTPS/CLI 为用户入口”已被 v1.1 覆盖 |
|
||
| 06 分层身份权限与凭据模型 | adopted-v1.1 | 飞书绑定内部用户、Gitea 绑定、双层授权、AgentSession 和服务身份采用 | 不建设通用企业管理系统，不透传三类 token |
|
||
| 07 业务线归属内容状态与流转 | adopted-with-superseded-sections | 内容状态、责任和 Agent 路由采用 | 第 7 节临时归属流程及第 8 节业务线选择问题已完成或失效 |
|
||
| 08 AI 权限控制与人机协同 | adopted-v1.1 | A0～A5、角色隔离、控制面隔离和输出规则采用 | A1/A2 默认；A3/A4 经用户绑定 MCP、精确确认和网关受控开放 |
|
||
| 09 安全隐私审计与事故响应 | adopted-v1.1 | 威胁模型、强制逐调用三主体审计和事故分级采用 | 审计查询可走 MCP；审计写入/删除不得成为普通工具 |
|
||
| 10 运行观测备份恢复与连续性 | adopted | 指标、告警、备份范围、恢复和降级采用 | SLO、RPO、RTO 是建议值，需用户确认后才成为承诺 |
|
||
| 11 接口契约数据模型与事件 | adopted-with-sample-fixes | 七类契约、错误和事件采用 | 样例中的 `business_line_id: temporary` 必须改为正式稳定 ID；`project_id` 待试点确认 |
|
||
| 12 试点方案决策清单与路线图 | adopted-with-status-fixes | Gate 0～5、试点范围、测试和止损采用 | D01 已完成、D02 已确认；成功标准中的“11 类样本”应为 12 类 |
|
||
|
||
## 4. 执行单分类
|
||
|
||
| 执行单 | 分类 | 当前状态 | 进入条件 |
|
||
|---|---|---|---|
|
||
| EXE-00 执行总览 | adopted | 已采用 | 作为总索引，不单独执行 |
|
||
| EXE-01 业务归属与试点 | future-implementation-gate | 业务线和 owner 已确认；EXE 尚未启动 | Verlit 明确进入实施后，再确认试点、成员、角色、服务器和证据落点 |
|
||
| EXE-02 契约与状态机 | adopted | blocked-by-parameters | 稳定 business_line_id、project_id 和正式代码库 |
|
||
| EXE-03 Gitea 基础层 | adopted | blocked-by-target | 指定服务器、网络、管理员、备份目标及远端执行授权 |
|
||
| EXE-04 身份角色权限 | adopted-v1.1 | local-design-ready | 飞书/内部/Gitea 绑定、双层权限和会话进入必需链；真实账号/数据库等待 C1/G0 对应授权 |
|
||
| EXE-05 来源选择与构建 | adopted | blocked-by-contracts | EXE-02、正式代码库和来源规则完成 |
|
||
| EXE-06 质量安全检查 | adopted | blocked-by-builder | EXE-02、EXE-05 和策略责任人完成 |
|
||
| EXE-07 发布网关 | adopted | blocked-by-foundation | EXE-02、03、04、06 通过 |
|
||
| EXE-08 current 导出 | adopted | blocked-by-gateway | EXE-03、EXE-07 通过 |
|
||
| EXE-09 MCP Gateway | required-v1.1 | blocked-by-identity-and-core | EXE-04、07、08 通过；生产远程 MCP，开发 STDIO；不建设自定义 Web |
|
||
| EXE-10 Agent 读取与读回 | adopted-v1.1 | blocked-by-mcp | EXE-08 提供内部 read port，EXE-09 提供唯一用户工具面 |
|
||
| EXE-11 监控备份事故 | adopted | blocked-by-target | 随 EXE-03 启动，真实试点前必须完成 |
|
||
| EXE-12 试点与 v2 判决 | adopted | blocked-by-gates | EXE-01～11 中适用门禁通过 |
|
||
| EXE-13 下发与证据规范 | adopted | ready | 后续每个实施任务必须使用 |
|
||
|
||
## 5. v1 基线与 v1.1 覆盖追溯矩阵
|
||
|
||
| 冻结原则 | 主方案依据 | 详细设计/执行消费者 | 验收证据 |
|
||
|---|---|---|---|
|
||
| 项目是业务容器，一项目一私有仓库 | 二、三、十 | 01、06、EXE-03/04 | 项目权限正反测试 |
|
||
| 个人材料单向明确发布，不做双向同步 | 二、六、十三 | 03、07、EXE-05 | selection 与未选内容测试 |
|
||
| 发布网关唯一写受保护 `main` | 四、六、十 | 04、06、EXE-03/07 | 分支保护与绕过测试 |
|
||
| `main/current` 是唯一默认读取面 | 二、三、五 | 04、07、EXE-08/10 | Git/current/readback 一致 |
|
||
| `discussion/confirmed` 与技术状态分离 | 七 | 04、07、11、EXE-02/07/10 | 状态解释与负面测试 |
|
||
| Agent 不持有写凭据；A3/A4 只提交受控网关请求 | v1 三、四、十三＋v1.1 九 | 05、08、EXE-04/09/10 | 工具权限、精确确认和提示注入测试 |
|
||
| 试点 `forced_off`，审核仅为条件分支 | 版本边界、十一 | 审核治理基线、EXE-02/07/12 | OFF 正常与模拟 ON 负面测试 |
|
||
| 恢复产生新 current 发布 | 九 | 04、10、EXE-08/11/12 | 恢复发布与空环境恢复 |
|
||
| MCP 是唯一用户业务入口，不建设自定义业务 Web | v1.1 三、八、十一 | 05、EXE-09/10 | M09/M10、工具注册表和旁路检查 |
|
||
| 飞书身份绑定内部用户，内部授权＋Gitea 权限双层限制 | v1.1 六、七 | 06、EXE-04/09 | M01～M04、撤权测试 |
|
||
| 飞书—Gitea 绑定不信任自报 username | v1.1 六、七＋闭环安全决策 | PRD S00/S03/S26、EXE-04 | 未绑定、冲突、停用和冒充负面测试 |
|
||
| 每次 MCP 调用强制记录 human＋agent＋service | v1.1 十 | 09、EXE-09/11 | M05/M06/M08 和审计完整性检查 |
|
||
| 中文检索只索引授权 current | v1 五、八＋闭环检索决策 | PRD S08/S21、EXE-08/10 | project/release 过滤、中文相关性和旧索引隔离测试 |
|
||
| Skill Registry、飞书内容来源和通用审批不进入当前目标 | v1.1 四、十三 | 03、12 | 工具/依赖清单无隐式前置 |
|
||
|
||
## 6. 防偏移检查
|
||
|
||
出现以下任一设计或实施提案时必须停止当前 v1.1 任务并重新决策：
|
||
|
||
- 直接修改 v1 原稿正文，或未通过差量版本说明静默覆盖 v1；
|
||
- 将 MCP 降回可选适配器，另建用户 Web/REST/CLI 业务入口或故障高权旁路；
|
||
- 用共享飞书机器人/Agent 身份代替真实用户绑定，或信任工具参数自报主体；
|
||
- 只检查内部权限或 Gitea 权限其中一层，任一层拒绝后仍放行；
|
||
- 将审计写入变成 Agent 可选调用，或允许动作成功但三主体审计缺失；
|
||
- 将 Skill Registry 或可执行 Skill 审核加入普通 Context 发布链；
|
||
- 在同一仓库内用目录或文档 ACL 模拟项目权限边界；
|
||
- 新增第三种 `content_status`，或把 `pending_review` 写成内容状态；
|
||
- 允许 Agent、publisher 或普通成员直接写 `main`；
|
||
- 创建第二个默认 current、在服务目录逐文件覆盖或让 Agent 扫描历史；
|
||
- 同步整个私人 Vault、私人 Git 历史或自动监听后发布；
|
||
- 用 MCP、prompt 或客户端 payload 覆盖服务端身份、权限和审核策略。
|
||
|
||
飞书身份、内部权限数据库和 MCP 已经属于 v1.1 必需能力；受控 Skill Registry、飞书内容来源和自定义 Web 仍需独立后续版本，不能隐式加入。
|
||
|
||
## 7. 更新规则
|
||
|
||
- 文档分类变化必须说明来源、改变范围、责任人和日期。
|
||
- `adopted` 文档的实现细节可以参数化，但不能静默改变冻结原则。
|
||
- v1.1 标为 required 的 MCP、身份、双层权限和强制审计不得在实现时降级为 optional。
|
||
- `superseded` 只表示相关段落失效，不删除历史证据。
|
||
- 新方案无法映射到本追溯矩阵时，默认属于版本变更而不是 v1 实现细节。
|