提交gitea知识库方案
This commit is contained in:
@@ -0,0 +1,367 @@
|
||||
---
|
||||
title: Gitea知识库 v1.1 开发任务分解
|
||||
date: 2026-08-07
|
||||
type: tasks
|
||||
status: draft
|
||||
content_status: discussion
|
||||
owner: Verlit
|
||||
last_updated_at: 2026-08-10
|
||||
last_updated_by: Codex
|
||||
hash: sha256:6d1468c5dae4cb8efcb80cda34d952106018a0b7db0f47054f18a3fab9f43a49
|
||||
hash_scope: Markdown 正文（从一级标题开始至文件末尾）的 UTF-8 SHA-256
|
||||
belongs_to:
|
||||
- "[[3-业务线/Gitea知识库/_context|Gitea知识库]]"
|
||||
depends_knowledge:
|
||||
- "[[3-业务线/Gitea知识库/v1-工程构建规格|v1 工程构建规格]]"
|
||||
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 验收与止损矩阵]]"
|
||||
---
|
||||
|
||||
# Gitea知识库 v1.1 开发任务分解
|
||||
|
||||
## 1. 使用边界
|
||||
|
||||
本文件是未来代码开发的可下发 backlog。当前只完成任务拆解，所有 `DEV-*` 均为 `planned`，没有创建代码仓库、编写代码、运行测试、连接 Gitea 或部署服务。
|
||||
|
||||
任务开工需同时满足：Verlit 明确宣布进入代码开发；平台代码仓库和技术栈已确认；任务有责任人、验收人、产物位置和停止条件。代码开发授权不自动包含服务器部署或真实试点授权。
|
||||
|
||||
## 2. 依赖总览
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
D00[DEV-00 开发基线] --> D01[DEV-01 契约包]
|
||||
D00 --> D02[DEV-02 领域内核]
|
||||
D01 --> D03[DEV-03 来源与选择]
|
||||
D02 --> D03
|
||||
D03 --> D04[DEV-04 确定性构建]
|
||||
D04 --> D05[DEV-05 检查门]
|
||||
D01 --> D06[DEV-06 身份、双层权限与策略]
|
||||
D02 --> D06
|
||||
D05 --> D07[DEV-07 发布事务]
|
||||
D06 --> D07
|
||||
D07 --> D08[DEV-08 Gitea适配]
|
||||
D08 --> D09[DEV-09 current导出]
|
||||
D09 --> D10[DEV-10 读取与读回]
|
||||
D06 --> D11[DEV-11 MCP Gateway]
|
||||
D10 --> D11
|
||||
D07 --> D12[DEV-12 审计与观测]
|
||||
D09 --> D12
|
||||
D10 --> D12
|
||||
D01 --> D13[DEV-13 测试工具链]
|
||||
D02 --> D13
|
||||
D03 --> D13
|
||||
D04 --> D13
|
||||
D05 --> D13
|
||||
D06 --> D13
|
||||
D07 --> D13
|
||||
D08 --> D13
|
||||
D09 --> D13
|
||||
D10 --> D13
|
||||
D11 --> D13
|
||||
D12 --> D13
|
||||
D13 --> D14[DEV-14 打包与交接]
|
||||
```
|
||||
|
||||
DEV-01 与 DEV-02 可以并行；DEV-03～06 可在契约稳定后部分并行；DEV-07～10 是发布闭环的串行主链。DEV-13 不是最后才写测试，而是从 DEV-01 开始持续提供 fixture、fake adapter 和测试规范，最终统一收口。
|
||||
|
||||
## 3. 批次与交付门
|
||||
|
||||
| 批次 | 任务 | 目标 | 批次完成门 |
|
||||
|---|---|---|---|
|
||||
| A 工程基线 | DEV-00～02 | 仓库纪律、契约和领域语义稳定 | schema、状态机和错误模型通过契约测试 |
|
||||
| B 本地内容链与身份门 | DEV-03～06 | 使用合成数据完成选择、构建、检查、身份和双层授权判断 | 不连接飞书/Gitea 也可完成确定性本地链路 |
|
||||
| C 发布闭环 | DEV-07～10 | 使用 fake Gitea/临时目录完成事务、导出和读回 | 并发、幂等、原子切换与失败状态可验证 |
|
||||
| D MCP、Agent 与保障 | DEV-11～13 | MCP 唯一工具面、强制审计、安全语料与观测测试完备 | Agent 只能受控调用；A3/A4 需精确确认；端到端覆盖硬边界 |
|
||||
| E 打包交接 | DEV-14 | 形成可供未来测试环境部署的制品和说明 | 制品可复现、无秘密、未自动连接任何环境 |
|
||||
|
||||
## 4. DEV-00——开发基线与仓库骨架
|
||||
|
||||
**目标**：把工程构建规格转成一个可维护但不绑定部署环境的代码仓库骨架。
|
||||
|
||||
**交付物**：
|
||||
|
||||
- README：目的、边界、模块图、开发命令和非目标；
|
||||
- `contracts/`、`src/`、`config/`、`tests/`、`packaging/`、`docs/` 逻辑目录；
|
||||
- 格式、静态检查、依赖锁定和测试入口；
|
||||
- 贡献规则、敏感信息禁入规则和提交检查；
|
||||
- 技术栈决策记录，不包含服务器与生产配置。
|
||||
- 运行时、编程语言、MCP SDK 和本地 STDIO 开发入口决策；不包含自定义 Web 前端。
|
||||
|
||||
**验收**：空骨架可以在离线/本地环境完成格式与最小测试；示例配置只含占位符；秘密扫描无发现。
|
||||
|
||||
**停止条件**：仓库归属不清、要求同时创建真实项目仓库、需要真实 token 才能完成骨架时停止。
|
||||
|
||||
## 5. DEV-01——v1＋v1.1 契约包
|
||||
|
||||
**目标**：把 Selection、Artifact、Validation、Release、Policy Snapshot、Current、Readback/Receipt、身份绑定、ProjectGrant、AgentSession、MCP Tool 和三主体 Audit Event 固化为机器可校验 schema。
|
||||
|
||||
**交付物**：
|
||||
|
||||
- 通用字段、actor namespace、稳定 ID、RFC3339、hash scope 定义；
|
||||
- 每类对象的 v1 schema、合法样例与非法样例；
|
||||
- `business_line_id` 使用正式稳定值规则，不再使用 `temporary`；
|
||||
- major/minor 兼容规则、未知关键状态拒绝规则；
|
||||
- 错误 envelope 与 `STALE_BASE` 等错误码清单；
|
||||
- `UserIdentity`、`FeishuBinding`、`GiteaBinding`、`ProjectGrant` 和 `AgentSession` schema；
|
||||
- MCP 工具输入/输出、确认引用，以及 human＋agent＋service 审计字段；
|
||||
- 契约生成物清单和版本说明。
|
||||
|
||||
**测试映射**：CT-01～CT-04。
|
||||
|
||||
**完成标准**：所有合法样例通过、非法样例按预期失败；任何字段变更可以被兼容性测试识别；契约中没有秘密和私人绝对路径。
|
||||
|
||||
## 6. DEV-02——领域内核与状态机
|
||||
|
||||
**目标**：建立不依赖 Gitea、MCP SDK 或数据库产品的稳定领域语义。
|
||||
|
||||
**交付物**：
|
||||
|
||||
- `discussion | confirmed` 内容状态；
|
||||
- `current | superseded | retired` 技术状态；
|
||||
- release 正常、异常和终止状态及允许转换表；
|
||||
- 稳定 ID 生成/解析、actor namespace、hash 与 canonicalization；
|
||||
- 幂等键、`base_current`、candidate hash 和错误分类值对象；
|
||||
- 非法跳转、completed 回退和未知 major version 的拒绝逻辑。
|
||||
|
||||
**测试映射**：UT-DOM-01～UT-DOM-08、CT-03。
|
||||
|
||||
**完成标准**：领域层无网络、文件系统、数据库和框架依赖；状态转换表达到分支全覆盖。
|
||||
|
||||
## 7. DEV-03——本地来源与明确选择
|
||||
|
||||
**目标**：只针对 v1 的本地 Markdown 来源，把人类明确选择转成不可变 Selection Manifest。
|
||||
|
||||
**交付物**：
|
||||
|
||||
- 文件、章节和多材料选择模型；
|
||||
- 来源 revision/hash 固定、排除项和允许根目录；
|
||||
- 路径规范化、越界、符号链接和控制文件预检查；
|
||||
- selection canonicalization 与 hash；
|
||||
- 不读取未选择文件的 fake/local source adapter。
|
||||
|
||||
**测试映射**：UT-SEL-01～06、SEC-PATH-01～04、T03、T05。
|
||||
|
||||
**完成标准**：同一输入产生相同 selection hash；相邻私密文件和越界路径不进入读取集合；不包含飞书来源适配器。
|
||||
|
||||
## 8. DEV-04——确定性内容构建器
|
||||
|
||||
**目标**：从 Selection Manifest 生成可复现的 Artifact Bundle。
|
||||
|
||||
**交付物**：
|
||||
|
||||
- Markdown 正文组合、稳定顺序和规范化规则；
|
||||
- 附件 allowlist、checksum、链接解析与改写；
|
||||
- Artifact Manifest、source refs、builder version；
|
||||
- 临时构建区生命周期和清理接口；
|
||||
- 两次相同构建产生一致 artifact hash 的验证工具。
|
||||
|
||||
**测试映射**：UT-BLD-01～08、IT-BLD-01、T03、T04。
|
||||
|
||||
**完成标准**：构建器不写 Gitea、不访问未选来源、不将临时绝对路径写入制品；相同输入和工具版本得到相同 manifest/hash。
|
||||
|
||||
## 9. DEV-05——质量与安全检查门
|
||||
|
||||
**目标**：在任何远端写入前，对构建物给出机器可判断且不可静默绕过的 Validation Report。
|
||||
|
||||
**交付物**：
|
||||
|
||||
- schema、frontmatter、Markdown、链接和附件检查；
|
||||
- 路径穿越、符号链接、控制文件和隐藏文件检查；
|
||||
- 凭据、PII 和敏感内容规则端口；
|
||||
- `pass | pass_with_warnings | blocked` 结果及 finding 模型；
|
||||
- 例外契约：规则 ID、原因、批准身份、有效期和独立审计；
|
||||
- 安全失败语料库，全部使用合成秘密和虚构个人数据。
|
||||
|
||||
**测试映射**：UT-VAL-01～10、SEC-DATA-01～08、T05、T07。
|
||||
|
||||
**完成标准**：blocking finding 不能由客户端布尔字段覆盖；日志和报告不回显完整秘密；检查失败时没有 release side effect。
|
||||
|
||||
## 10. DEV-06——飞书身份绑定、双层权限与项目策略
|
||||
|
||||
**目标**：实现飞书登录身份到内部稳定用户及 Gitea 账户的绑定模型，并定义内部 ProjectGrant 第一层、Gitea 项目权限第二层和发布策略端口；不建设通用企业管理系统。
|
||||
|
||||
**交付物**：
|
||||
|
||||
- UserIdentity、FeishuBinding、GiteaBinding、ProjectGrant、AgentSession 和 ServiceIdentity 端口；
|
||||
- 从已验证会话派生 user/agent/client，拒绝工具参数冒充身份；
|
||||
- project、actor、role、action、resource 的双层授权请求/结果；
|
||||
- Gitea 项目成员/读取资格复核端口与 `permission_mismatch`；
|
||||
- review policy version、hash 和 snapshot；
|
||||
- 试点 `forced_off` 正常逻辑及隔离的模拟 ON 逻辑；
|
||||
- client payload 禁止覆盖策略字段的校验；
|
||||
- fake identity/grant/Gitea permission/policy store 和合成身份夹具；
|
||||
- project 配置变化的 CAS 与审计事件。
|
||||
|
||||
**测试映射**：UT-POL-01～08、SEC-AUTH-01～06、T02。
|
||||
|
||||
**完成标准**：publisher/Agent 无法自报或修改身份、授权和策略；任一权限层拒绝都 fail closed；会话、绑定或授权撤销后未来访问立即失败；本地开发不调用真实飞书或 Gitea。
|
||||
|
||||
## 11. DEV-07——发布网关与事务编排
|
||||
|
||||
**目标**：实现 release 请求的鉴权、幂等、CAS、状态机编排和最终回执，不直接绑定特定 Gitea SDK。
|
||||
|
||||
**交付物**：
|
||||
|
||||
- `release.request`、`release.get` 逻辑端口；
|
||||
- 调用主体只接受 MCP 验证上下文，不接受 payload 自报用户、角色或 grant；
|
||||
- release record store port 与 fake/in-memory adapter；
|
||||
- idempotency、`base_current`、candidate hash 和超时处理；
|
||||
- validation/policy 前置检查；
|
||||
- Gitea、export、readback 端口编排；
|
||||
- Git/导出/读回分段结果和 publish receipt；
|
||||
- 每一步的 correlation/audit event。
|
||||
|
||||
**测试映射**：UT-REL-01～12、IT-REL-01～08、T01、T02、T06、T09、T11。
|
||||
|
||||
**完成标准**：相同幂等键不产生第二个逻辑发布；stale base 不自动 merge；导出或读回失败绝不返回 completed。
|
||||
|
||||
## 12. DEV-08——Gitea 项目仓库适配器
|
||||
|
||||
**目标**：把网关端口映射到 Gitea 项目级 Git/API 能力，同时保持最小权限和可替换性。
|
||||
|
||||
**交付物**：
|
||||
|
||||
- 读取 main/ref、比较 CAS、写 commit/tag 的端口实现；
|
||||
- 项目仓库映射和 credential reference；
|
||||
- 统一错误映射、超时、重试与脱敏；
|
||||
- fake Gitea adapter；
|
||||
- 可选的测试环境 adapter 配置模板，不包含真实地址和凭据。
|
||||
|
||||
**测试映射**：IT-GIT-01～08、SEC-AUTH-07～10、T06、T10。
|
||||
|
||||
**完成标准**：适配器没有全局用户/组织管理能力；凭据不进入日志、错误和对象；普通测试默认使用 fake adapter。
|
||||
|
||||
## 13. DEV-09——current 导出器
|
||||
|
||||
**目标**：从指定 commit 构建只读 release 目录，并保证读取者只看到完整旧版或完整新版。
|
||||
|
||||
**交付物**：
|
||||
|
||||
- release staging、manifest/checksum 校验；
|
||||
- `releases/<release-id>/` 与唯一 current 指针抽象；
|
||||
- 原子 rename/symlink 端口及跨平台 fake；
|
||||
- 切换失败、回切和清理策略；
|
||||
- Current Manifest 生成与签名/hash；
|
||||
- 同时有效 current 数量检查。
|
||||
|
||||
**测试映射**：UT-EXP-01～08、IT-EXP-01～06、T09、T11。
|
||||
|
||||
**完成标准**：不存在逐文件覆盖服务中 current 的路径；任何时刻只有一个有效 current；失败不破坏上一个已验证版本。
|
||||
|
||||
## 14. DEV-10——项目内部读取端口与读回
|
||||
|
||||
**目标**：提供按项目授权读取 Current Manifest/artifact 的内部端口，并为发布网关提供正式读回结果；用户访问由 DEV-11 MCP 工具面承接。
|
||||
|
||||
**交付物**：
|
||||
|
||||
- `current.manifest.get`、`current.artifact.get`、`readback.verify` 逻辑端口；
|
||||
- 项目身份与统一拒绝策略；
|
||||
- artifact allowlist、缓存版本键和禁止枚举规则；
|
||||
- Git、current、读取入口三段比对；
|
||||
- Readback Report 及 readback failure 分类。
|
||||
|
||||
**测试映射**：UT-READ-01～08、IT-RBK-01～06、SEC-AUTH-11～14、T09、T10。
|
||||
|
||||
**完成标准**：未授权项目、Git 历史、控制面、staging 和失败包不可读；缓存不能返回与 manifest 不同版本；读回失败阻断 completed。
|
||||
|
||||
## 15. DEV-11——MCP Gateway 与全员 Agent 工具面
|
||||
|
||||
**目标**：让已完成飞书身份绑定的员工通过 Agent Host 只使用 MCP 完成授权范围内的读取、构建、验证、受控发布和审计查询，不建设自定义业务 Web 页面。
|
||||
|
||||
**交付物**：
|
||||
|
||||
- 远程 MCP 生产入口、STDIO 本地开发入口和版本化工具 registry；
|
||||
- `get_my_identity`、授权项目、current 读取/搜索、构建/验证/diff、发布请求、状态和审计查询工具；
|
||||
- 已验证用户＋Agent＋client 会话到 read/build/release 端口的映射；
|
||||
- manifest allowlist 驱动的 Context 装载；
|
||||
- project、release、artifact、hash、`content_status` 输出引用；
|
||||
- discussion 显著标记和 confirmed 冲突停止规则；
|
||||
- prompt injection 与跨项目请求的拒绝夹具；
|
||||
- A1/A2 默认允许，A3/A4 绑定精确确认、candidate hash、`base_current` 和会话；
|
||||
- 禁止审计写入/删除、权限写入、Gitea Admin/直接 push、SSH、SQL、部署、备份、密钥和策略开关的能力清单；
|
||||
- MCP 失败不回退到共享 CLI、通用 token、shell 或其他用户业务入口。
|
||||
|
||||
**测试映射**：UT-AGT-01～08、SEC-INJ-01～06、T08、T10。
|
||||
|
||||
**完成标准**：恶意正文不能增加工具或权限；Agent 无法冒充用户、读取未授权项目或历史；A2 不产生远端状态；A3/A4 只有精确确认后才能提交网关；没有可用的自定义 Web/REST/CLI 用户入口。
|
||||
|
||||
## 16. DEV-12——审计、指标与告警端口
|
||||
|
||||
**目标**：由服务端中间件强制记录每次 MCP 调用及业务阶段的 human＋agent＋service 行为链，同时不绑定具体监控产品。
|
||||
|
||||
**交付物**：
|
||||
|
||||
- MCP `request_received`、授权 allowed/denied、completed/failed 自动事件；
|
||||
- human_actor、agent_actor、service_actor、session、tool、action、request hash 和 confirmation 的强制字段；
|
||||
- Audit Event emitter、outbox/等价可靠写入与 append-only store port；
|
||||
- correlation/release/project 查询模型；
|
||||
- 健康、阶段耗时、失败、stale base、current 不一致、撤权和备份年龄指标；
|
||||
- 告警路由端口、去重和关闭状态；
|
||||
- 日志字段 allowlist 与秘密脱敏测试；
|
||||
- 事故事件与 release/current 的关联规则；
|
||||
- 审计查询 MCP 端口；不提供普通 MCP 审计写入、更新和删除工具。
|
||||
|
||||
**测试映射**：UT-AUD-01～08、IT-OBS-01～05、SEC-LOG-01～05。
|
||||
|
||||
**完成标准**：每个 read/search/build/validate/publish/cancel/denied 都能用 correlation ID 串起三主体行为链；业务写和审计不可持久化时 fail closed；日志不含正文、秘密和非必要个人信息。
|
||||
|
||||
## 17. DEV-13——统一测试工具链与端到端夹具
|
||||
|
||||
**目标**：将各任务测试统一为可重复、默认离线、不触达真实环境的验证体系。
|
||||
|
||||
**交付物**：
|
||||
|
||||
- schema test runner、fixture builder、synthetic identity、fake source/Gitea/permission/policy/read endpoint；
|
||||
- 状态机、并发、幂等和原子文件系统测试工具；
|
||||
- 合成安全语料和 prompt injection 语料；
|
||||
- 身份冒充、双层权限不一致、会话/绑定/授权撤销和审计中断场景；
|
||||
- happy path、每个异常状态和恢复发布的端到端场景；
|
||||
- 测试结果清单：用例 ID、契约版本、fixture hash、结果和关联任务；
|
||||
- 与 `v1-验收与止损矩阵.md` 的覆盖映射报告。
|
||||
|
||||
**测试映射**：CT、UT、IT、SEC 全集；真实恢复和 T01～T12 仅在未来对应环境执行。
|
||||
|
||||
**完成标准**：默认测试不需要网络、真实账号或秘密；必需模块和 v1/v1.1 硬边界均有正反测试；失败结果可定位到模块与契约。
|
||||
|
||||
## 18. DEV-14——可复现打包与开发交接
|
||||
|
||||
**目标**：形成未来可以交给测试环境部署任务使用的版本制品，但不执行部署。
|
||||
|
||||
**交付物**：
|
||||
|
||||
- 版本号、依赖锁、SBOM/依赖清单和制品 checksum；
|
||||
- 示例配置与秘密引用说明；
|
||||
- 数据迁移/契约兼容说明；
|
||||
- 操作入口、健康检查和回滚接口说明；
|
||||
- MCP tools manifest、身份/权限迁移说明和审计 schema；
|
||||
- 已知限制、未决实施参数和安全边界；
|
||||
- 构建报告与测试覆盖映射。
|
||||
|
||||
**验收**：从干净开发环境可复现相同制品 hash；包内不存在真实地址、账号、项目数据或秘密；制品不会自动连接服务器或 Gitea。
|
||||
|
||||
## 19. 可选任务
|
||||
|
||||
| ID | 任务 | 启动条件 | v1 地位 |
|
||||
|---|---|---|---|
|
||||
| DEV-90 | 本地 STDIO 开发适配器增强 | 开发调试需要且复用远程 MCP 相同中间件 | optional，不替代远程 MCP 目标 |
|
||||
| DEV-91 | 自定义业务 Web/发布驾驶舱 | 当前明确关闭；只有另立版本并重新确认产品入口才可启动 | 不属于 v1.1 |
|
||||
| DEV-92 | 飞书内容来源适配器 | 身份方案稳定后另立内容来源版本 | 不属于 v1.1 |
|
||||
| DEV-94 | Skill Registry | Context 发布闭环稳定后形成独立审核与供应链方案 | 不属于当前 v1 |
|
||||
|
||||
飞书身份绑定、内部权限数据库、Gitea 二次复核、MCP 和强制审计已进入 DEV-00～14 必需链，不再作为可选任务。其余可选任务不得成为 DEV-00～14 的隐式依赖。
|
||||
|
||||
## 20. 单任务正式下发要求
|
||||
|
||||
未来将某个 DEV 任务改为 `in_progress` 前，必须补齐：
|
||||
|
||||
- 平台代码仓库、目标分支和允许修改的目录；
|
||||
- 主责任人、协作人和验收人；
|
||||
- 技术栈、最低版本和依赖添加规则；
|
||||
- 输入契约、交付文件和测试 ID；
|
||||
- 禁止动作、秘密处理、停止条件和回滚方式；
|
||||
- 证据位置及完成后的正文/hash 更新责任。
|
||||
|
||||
未满足这些条件时，本文件保持规划状态，不能把“任务已拆解”解释为“代码已经开始开发”。
|
||||
Reference in New Issue
Block a user