359 lines
20 KiB
Markdown
359 lines
20 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:bcb8ad1f91c65098440d6d52606382c01e0f6cecc7227fe4298815ebb02b18bf
|
||
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 详细实施方案]]"
|
||
- "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. 逻辑组件与依赖
|
||
|
||
```mermaid
|
||
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 平台代码仓库逻辑结构
|
||
|
||
以下是逻辑结构，不代表已经创建实际目录：
|
||
|
||
```text
|
||
<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 仓库固定结构
|
||
|
||
```text
|
||
<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 事务状态
|
||
|
||
```text
|
||
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、真实账号和试点项目继续由未来实施准入门控制。
|