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	设计spec	draft	discussion	Verlit	2026-08-10	Codex	sha256:bcb8ad1f91c65098440d6d52606382c01e0f6cecc7227fe4298815ebb02b18bf	Markdown 正文（从一级标题开始至文件末尾）的 UTF-8 SHA-256	3-业务线/Gitea知识库/_context		3-业务线/Gitea知识库/公司共享 Context 项目仓库发布方案 v1 3-业务线/Gitea知识库/公司共享 Context MCP-first 身份与审计方案 v1.1 3-业务线/Gitea知识库/v1-设计追溯与版本关系 3-业务线/Gitea知识库/v1-详细实施方案 0-收集箱/临时待归属/2026-08-03-公司共享Context发布与AI协同框架/2026-08-03-01-总体架构与模块边界.md 0-收集箱/临时待归属/2026-08-03-公司共享Context发布与AI协同框架/2026-08-03-11-接口契约数据模型与事件.md

Gitea知识库 v1.1 工程构建规格

1. 文档定位

本文件定义 v1 基线叠加 v1.1 MCP-first 身份与审计覆盖层后，未来进入代码开发时的工程边界、逻辑仓库结构、模块依赖、契约落点、配置安全模型和构建测试要求。当前只形成设计规格，不创建代码仓库、不选择服务器、不部署服务、不连接 Gitea，也不运行真实发布链。

它不替代 v1 主方案：主方案回答“为什么建、业务边界是什么”；本文件回答“工程代码应如何组织，模块之间如何保持可替换和可测试”。

2. 当前构建阶段的完成定义

当前构建阶段完成时，应满足：

1. 每个必需模块的职责、输入、输出、禁止动作和依赖方向明确；
2. 平台代码仓库与项目 Context 仓库的概念完全分离；
3. 七类以上核心契约有固定逻辑落点、生产者、消费者和版本策略；
4. 发布事务、内容状态、技术状态和审核状态不混用；
5. 非敏感配置、项目控制配置和秘密引用分层；
6. 单元、契约、集成、安全、恢复和试点测试可以从任务映射到验收证据；
7. 未选择技术栈、服务器和试点项目时，工程方案仍然完整且不伪造环境参数；
8. 后续开发者可以按任务包开工，不需要重新设计 v1 核心架构。

达到这些条件只表示“具备未来开发条件”，不表示已经开始实施。

3. 不可变工程边界

• 一项目一私有 Context 仓库；项目仓库是内容与权限容器，不是平台源代码仓库。
• 平台代码不能通过目录 ACL 替代 Gitea 项目级权限边界。
• 来源选择、构建和检查均不持有 Gitea 写凭据。
• 发布网关是受保护 main 的唯一写入者；Gitea 适配器只能被网关调用。
• main/current 是唯一默认读取面；读取模块不遍历 .git、历史、staging 或失败包。
• discussion / confirmed 只表示内容状态；release 事务使用独立状态机。
• Agent 默认 A1/A2；A3/A4 只通过用户绑定 MCP 和精确确认提交受控网关请求，不获得 Git 写、SSH 或管理员凭据。
• v1.1 以远程 MCP 作为全员 Agent 的唯一用户业务入口，以飞书登录绑定、内部权限数据库、Gitea 权限复核和强制审计作为必需链路；Skill Registry、飞书内容来源、通用审批和自建 Web 页面仍不进入本版本。

4. 逻辑组件与依赖

flowchart LR
  C[contracts/domain] --> I[identity]
  C --> Z[authorization]
  C --> M[mcp-gateway]
  C --> S[selection]
  C --> B[builder]
  C --> V[validation]
  C --> P[policy]
  C --> R[release]
  C --> E[export]
  C --> Q[read/readback]
  I --> M
  Z --> M
  M --> S
  M --> B
  M --> R
  M --> Q
  S --> B --> V --> R
  P --> Z
  P --> R
  R --> G[gitea adapter]
  G --> E --> Q
  R --> A[audit ports]
  E --> A
  Q --> A
  M --> A

只允许上图方向的依赖。模块通过版本化对象和端口连接，不得直接读取其他模块私有数据库、缓存或工作目录。

逻辑模块	单一职责	主要输入	主要输出	明确禁止
domain	稳定 ID、枚举、状态机、hash 与错误语义	无外部资源	领域类型和校验规则	依赖框架、Gitea 或数据库
contracts	schema、样例、兼容策略和契约测试	领域类型	版本化契约包	保存秘密或环境地址
identity	飞书身份绑定、内部主体、Gitea 绑定和 AgentSession	已验证登录声明、绑定记录	稳定 user_id、会话主体链	信任工具参数中的用户身份、保存明文 token
authorization	内部 ProjectGrant、动作策略和 Gitea 项目权限复核	稳定主体、project、action、resource	双层授权决策和策略版本	任一层拒绝后降级到共享账号或高权凭据
mcp-gateway	提供唯一用户业务工具面并强制身份、确认、鉴权和审计中间件	用户绑定 MCP 会话、工具请求	版本化工具结果、关联 ID	暴露通用 Git/SQL/SSH/部署/审计写入能力
selection	将人类明确选择固化为允许读取范围	本地来源标识、选择范围	selection manifest	扫描整个私人工作区、自动发布
builder	确定性生成 artifact bundle	selection、标准化来源对象	artifact manifest、bundle	写 Gitea、改变业务状态
validation	结构、链接、路径、凭据、隐私和策略检查	artifact bundle、策略版本	validation report	静默修正业务语义、删除 finding
policy	读取受保护的项目策略和审核快照	project、策略基线	policy snapshot、决策结果	接受客户端传入的权威策略覆盖
release	鉴权、幂等、CAS、事务编排和回执	release request、validation、policy	release record、receipt、事件	直接读取私人来源、管理全局用户
gitea-adapter	在最小权限下读写指定项目仓库	网关端口调用	commit、ref、仓库状态	暴露 token、拥有全局管理员权限
export	从指定 commit 构建 staging 并原子切换 current	release、commit	current manifest、切换结果	在服务中的 current 内逐文件覆盖
read	按项目身份提供 current 和 manifest	project identity、读取请求	只读 artifact、版本元数据	暴露 Git 历史、控制配置和构建区
readback	发布后从正式读取面验证版本与状态	release、current endpoint	readback report	使用构建缓存假装正式读回
agent-session	约束哪个 Agent 代表哪个登录用户和 client	已验证用户、Agent/Host、会话声明	短期 AgentSession 与主体链	切换用户、自签身份或持有发布凭据
audit	自动追加三主体事件并提供授权只读查询	MCP 与业务链路 audit event	审计索引、关联查询和完整性证明	由 Agent 选择是否写入、修改/删除事件、成为业务或权限真源
observability	指标、健康检查和告警适配	运行指标和事件	指标、告警通知	记录正文、token 或私钥

review 在试点 forced_off 下不是独立人工审批服务；v1.1 仍保留策略快照与模拟 ON 的负面路径。远程 MCP 是生产目标的必需用户入口，STDIO 只用于本地开发；两者复用相同业务核心、双层授权与审计中间件。本项目不建设自定义业务 Web 页面。

5. 代码仓库与目录规划

5.1 两类仓库必须分离

仓库类型	作用	数量模型	是否在当前创建
平台代码仓库	保存上述模块、契约、测试和打包配置	v1 可采用一个模块化代码仓库起步	否，待正式进入开发并确认归属后创建
项目 Context 仓库	保存某个业务项目的 main/current、schema 和 Git 历史	一项目一私有仓库	否，待实施准入与试点确认后创建

“一项目一仓”约束针对项目 Context 仓库，不要求把平台每个代码模块拆成独立 Git 仓库。v1 初期优先保持一个模块化平台代码仓库，只有出现独立生命周期、权限或发布节奏后才拆仓。

5.2 平台代码仓库逻辑结构

以下是逻辑结构，不代表已经创建实际目录：

<platform-code-repo>/
├─ README.md
├─ contracts/
│  ├─ v1/
│  │  ├─ common/
│  │  ├─ selection/
│  │  ├─ artifact/
│  │  ├─ validation/
│  │  ├─ release/
│  │  ├─ current/
│  │  └─ readback/
│  └─ v1.1/
│     ├─ identity/
│     ├─ authorization/
│     ├─ mcp/
│     └─ audit/
├─ src/
│  ├─ domain/
│  ├─ identity/
│  ├─ authorization/
│  ├─ mcp/
│  ├─ selection/
│  ├─ builder/
│  ├─ validation/
│  ├─ policy/
│  ├─ release/
│  ├─ adapters/gitea/
│  ├─ export/
│  ├─ read/
│  ├─ readback/
│  ├─ agent-session/
│  ├─ audit/
│  └─ observability/
├─ config/
│  ├─ defaults.example.yaml
│  ├─ project.example.yaml
│  ├─ policy.example.yaml
│  ├─ identity.example.yaml
│  ├─ mcp.example.yaml
│  └─ audit.example.yaml
├─ tests/
│  ├─ contract/
│  ├─ unit/
│  ├─ integration/
│  ├─ identity/
│  ├─ mcp/
│  ├─ audit/
│  ├─ security-corpus/
│  ├─ recovery/
│  └─ fixtures/
├─ packaging/
├─ docs/
└─ tools/

目录名可以随技术栈调整，但职责边界、依赖方向和契约分层不能改变。

5.3 项目 Context 仓库固定结构

<project-id>-context/
├─ README.md
├─ current/
│  ├─ context.md
│  ├─ decisions/
│  ├─ assets/
│  └─ _release.yaml
├─ schema/
│  └─ context.schema.yaml
└─ .gitignore

平台代码、运行日志、构建缓存、秘密和私人来源均不得写入项目 Context 仓库。

6. 契约与数据所有权

对象	权威生产者	主要消费者	不可变性与落点要求
UserIdentity/Bindings	identity	authorization、MCP	内部稳定 ID；飞书/Gitea 绑定变更必须版本化并审计
ProjectGrant	authorization	MCP、release、read	第一层权限真源；不能由工具参数或 release payload 覆盖
AgentSession	identity	MCP、审计	短期、绑定 user/agent/client；过期或撤销后立即拒绝
Selection Manifest	selection	builder、审计	创建后不可修改；变化产生新 selection_id
Artifact Manifest/Bundle	builder	validation、release	绑定 selection 与 builder version；内容由 hash 固定
Validation Report	validation	release、审计	绑定 bundle 与 policy version；例外单独留痕
Release Request	发布客户端/未来入口	release	客户端提交意图，不得携带权威审核策略
Review Policy Snapshot	policy	release	网关接受请求时读取并固化；发布物不可覆盖
Release Record	release	export、readback、审计	事务状态真源；同一 release 顺序转换
Git Commit/Tag	Gitea	export、恢复流程	内容版本真源；失败 commit 不等于 completed
Current Manifest	export	read、readback、Agent	唯一 current 的读取真源；原子切换
Readback Report/Receipt	readback/release	发布者、审计	四段一致后才允许 final status 为 completed
MCP Tool Request/Result	mcp-gateway	业务模块、审计	从已验证会话派生主体；参数中的身份不具权威性
Audit Event	MCP 中间件与各模块	audit、监控	human＋agent＋service 三主体追加写；不含秘密、正文和私人绝对路径

所有对象必须包含或可追溯到：schema_version、稳定对象 ID、正式 business_line_id、project_id、RFC3339 时间、actor namespace、correlation_id 和声明 scope 的 SHA-256。

7. 状态模型

7.1 内容与技术状态

• 内容状态仅为 discussion | confirmed。
• 技术版本状态使用 current | superseded | retired。
• 两者是正交轴；进入 current 不等于 confirmed。

7.2 Release 事务状态

prepared
  → validating
  → ready
  → policy_evaluating
      ├─ not required ──────────────────────────┐
      └─ required → pending_review → approved ──┤
                                                ↓
                                             committing
  → committed
  → exporting
  → switched
  → reading_back
  → completed

终止或异常状态：rejected、review_rejected、stale_policy、stale_base、validation_failed、commit_failed、export_failed、readback_failed、cancelled。

状态机实现必须拒绝未知状态、跳跃转换和 completed 后回退。恢复旧内容必须创建新 release，不能改写历史状态。

8. 稳定逻辑操作

传输协议、框架和命令名称可以在开发开工时选择，但下列操作语义必须稳定：

Operation ID	调用者	输入	输出/错误
identity.get_current	登录用户/Agent	已验证 MCP 会话	内部用户、绑定和会话摘要
project.list_authorized	登录用户/Agent	已验证 MCP 会话	双层授权后可见项目集合
selection.create	人类入口	project、来源版本、范围、排除项、目标状态	selection manifest 或范围错误
artifact.build	构建协调器	selection manifest	bundle、artifact manifest 或确定性构建错误
validation.run	构建协调器	bundle、policy version	validation report
release.request	publisher 入口	release request、幂等键、base_current	release record 或权限/策略/CAS 错误
release.get	publisher/运维只读端	release ID	当前事务状态和可公开错误
current.switch	release 网关	project、commit、release manifest	current manifest 或 export error
current.manifest.get	人/Agent 读取端	project identity	授权项目 current manifest
current.artifact.get	人/Agent 读取端	project、artifact、current version	授权 artifact 或统一拒绝
readback.verify	release 网关	release、commit、manifest hash	readback report
audit.query	授权审计者	correlation/release/project、时间范围	脱敏事件集合

上述业务操作通过 MCP 工具对用户和 Agent 暴露；模块内部仍可使用进程内端口、队列或受控 HTTP。不得另建面向用户的 Web/REST/CLI 业务入口，也不得因传输方式改变鉴权、状态和错误语义。运维控制面不属于普通 MCP 工具面。

9. 配置与秘密边界

9.1 配置分层

层级	示例	真源与写权限
编译/默认配置	schema 版本、支持的状态、默认超时	平台代码仓库；代码评审后变更
环境非敏感配置	日志级别、端口、工作目录、公开域名占位	部署配置；不含真实秘密
项目控制配置	project ID、仓库映射、成员角色、review mode、敏感级别	受保护控制面；publisher/Agent 不可写
身份与授权配置	飞书 issuer/audience、MCP resource、binding policy、session TTL、Gitea 复核策略	身份/权限控制面；客户端和正文不可写
审计配置	事件 schema、outbox、保留策略、脱敏策略	审计控制面；普通业务主体只读授权范围
策略包	结构、链接、路径、秘密和 PII 检查规则	版本化策略真源；每次报告记录版本
秘密引用	Gitea project token、签名密钥、只读凭据	独立密钥系统；配置只保存引用，不保存值

9.2 必须禁止

• 不在 Markdown、schema、样例、环境文件、日志、测试夹具和 _runtime 中保存真实 token、cookie、私钥或密码。
• 不允许 release payload 修改 review mode、reviewer、权限矩阵或项目仓库映射。
• 不允许 Agent 通过正文提示改变项目路由、工具白名单或 credential reference。
• 不允许多个项目共享同一个可写凭据；只读凭据也必须能够独立撤销和轮换。
• 不使用客户端隐藏字段代替服务端鉴权和策略判断。
• 不接受工具参数自报 user_id、role、grant、AgentSession 或 review mode；主体只能从已验证会话派生。
• 不在飞书 token、MCP access token 和 Gitea 凭据之间做透传或复用。
• 不允许审计写入失败后继续执行业务动作，也不提供回退到共享账号、通用 CLI 或高权限 shell 的路径。

10. 工程构建与测试流水线规格

未来代码仓库的本地/CI 流水线按以下顺序设计；当前不创建也不运行流水线：

1. 格式与静态检查；
2. schema 与样例校验；
3. 契约兼容性检查；
4. 身份绑定、双层授权、MCP schema 和三主体审计契约测试；
5. 领域状态机和模块单元测试；
6. 使用 synthetic identity、fake source、fake Gitea 和临时目录的集成测试；
7. 身份冒充、越权、审计中断和安全失败语料测试；
8. 并发、幂等、原子切换和读回失败测试；
9. 构建可复现性与制品清单生成；
10. 只有后续获得明确授权，才允许测试环境连接真实 Gitea 或飞书身份环境；生产环境永不作为普通 CI 测试目标。

每个测试必须记录用例 ID、契约版本、输入 fixture hash、结果、错误码和关联开发任务。详细用例分层以 v1-验收与止损矩阵.md 为准。

11. 当前不需要确认的事项

以下参数留到正式开发或实施准入时决定，不阻断当前工程设计：

• 编程语言、MCP SDK、依赖注入和测试框架；
• 单体进程还是少量独立服务；
• Agent Host 及其飞书登录集成方式；
• 远程 MCP transport、OAuth/身份代理、协议版本和 token 生命周期；
• 身份权限数据库、release 状态库和 append-only audit store 的具体产品；
• Gitea 版本、部署方式、域名、端口和服务器目录；
• current 使用 HTTP、挂载或两者兼有；
• 日志、指标、告警和秘密系统的具体产品；
• 首个试点项目、真实成员、账号和仓库名称。

这里没有 Web 框架选型项，因为 v1.1 不建设自定义业务 Web 页面；远程 MCP 的 HTTP transport 不等于业务 Web 应用。这些选择不得改变第 3 节的不可变边界。若某个技术选择无法满足边界，应更换技术方案，而不是修改 v1/v1.1 语义。

12. 构建阶段交付清单

交付项	当前载体	状态
v1 业务与架构基线	公司共享 Context 项目仓库发布方案 v1.md	已完成
v1.1 MCP-first 身份与审计覆盖层	公司共享 Context MCP-first 身份与审计方案 v1.1.md	已完成草案
v1.1 推荐技术栈与详细实施设计	v1.1-技术栈与详细实施设计.md	Go/PostgreSQL/Gitea 推荐基线已形成；待 C1-00 验证 Agent Host
设计采用与防偏移追溯	v1-设计追溯与版本关系.md	已完成
工程模块、仓库、契约与配置规格	当前文件	已完成初版
未来开发任务包	v1-开发任务分解.md	与本规格配套
工程测试与系统验收规格	v1-验收与止损矩阵.md	已形成，补充工程测试层级
未来实施顺序	v1-详细实施方案.md	已完成环境无关部分
未来实施准入参数	v1-实施参数与决策清单.md	待进入实施前确认

13. 进入代码开发前的检查门

只有 Verlit 明确宣布进入代码开发后，才需要：

1. 确认平台代码仓库的正式归属、名称和维护者；
2. 选择运行时、编程语言、MCP SDK 及最低支持版本，不选择自建 Web 前端框架；
3. 确认 Agent Host、飞书登录集成、远程 MCP 认证、身份权限库和审计存储的技术边界；
4. 确认开发环境只使用合成身份、合成数据和 fake adapter；
5. 将 v1-开发任务分解.md 中的首批任务正式下发；
6. 为代码修改建立独立任务、验收人和产物位置。

确认以上事项仍不等于授权部署。服务器、Gitea、真实账号和试点项目继续由未来实施准入门控制。