test-doc/Gitea知识库/v1-开发任务分解.md

title, date, type, status, content_status, owner, last_updated_at, last_updated_by, hash, hash_scope, belongs_to, depends_knowledge, source_refs

title	date	type	status	content_status	owner	last_updated_at	last_updated_by	hash	hash_scope	belongs_to	depends_knowledge	source_refs
Gitea知识库 v1.1 开发任务分解	2026-08-07	tasks	draft	discussion	Verlit	2026-08-10	Codex	sha256:6d1468c5dae4cb8efcb80cda34d952106018a0b7db0f47054f18a3fab9f43a49	Markdown 正文（从一级标题开始至文件末尾）的 UTF-8 SHA-256	3-业务线/Gitea知识库/_context	3-业务线/Gitea知识库/v1-工程构建规格	3-业务线/Gitea知识库/公司共享 Context 项目仓库发布方案 v1 3-业务线/Gitea知识库/公司共享 Context MCP-first 身份与审计方案 v1.1 3-业务线/Gitea知识库/v1-详细实施方案 3-业务线/Gitea知识库/v1-验收与止损矩阵

Gitea知识库 v1.1 开发任务分解

1. 使用边界

本文件是未来代码开发的可下发 backlog。当前只完成任务拆解，所有 DEV-* 均为 planned，没有创建代码仓库、编写代码、运行测试、连接 Gitea 或部署服务。

任务开工需同时满足：Verlit 明确宣布进入代码开发；平台代码仓库和技术栈已确认；任务有责任人、验收人、产物位置和停止条件。代码开发授权不自动包含服务器部署或真实试点授权。

2. 依赖总览

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 更新责任。

未满足这些条件时，本文件保持规划状态，不能把“任务已拆解”解释为“代码已经开始开发”。