174 lines
12 KiB
Markdown
174 lines
12 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:292dd18325e826b1b05080326964a36078f510d4ba7dd4839b25eaf134d1f104
|
||
hash_scope: Markdown 正文（从一级标题开始至文件末尾）的 UTF-8 SHA-256
|
||
belongs_to:
|
||
- "[[3-业务线/Gitea知识库/_context|Gitea知识库]]"
|
||
source_refs:
|
||
- "[[3-业务线/Gitea知识库/公司共享 Context 项目仓库发布方案 v1|公司共享 Context 项目仓库发布方案 v1]]"
|
||
- "[[3-业务线/Gitea知识库/公司共享 Context MCP-first 身份与审计方案 v1.1|公司共享 Context MCP-first 身份与审计方案 v1.1]]"
|
||
- "0-收集箱/临时待归属/2026-08-03-公司共享Context发布与AI协同框架/2026-08-03-12-试点方案决策清单与路线图.md"
|
||
---
|
||
|
||
# Gitea知识库 v1.1 实施参数与决策清单
|
||
|
||
## 1. 使用规则
|
||
|
||
本文件只记录未来从冻结设计进入代码开发或真实实施时仍缺少的参数。它不是当前 `C0 工程设计构建` 的待办清单，也不要求 Verlit 现在确认试点和服务器。已冻结模型不重新征求选择；推荐值在 Verlit 确认前不是批准参数。参数缺失时可以继续做本地设计整理，但不得创建远端资源或生成针对未知环境的部署命令。
|
||
|
||
## 2. 已确认的 v1＋v1.1 决策
|
||
|
||
| ID | 决策 | 当前值 | 状态 |
|
||
|---|---|---|---|
|
||
| D01 | 正式业务线 | `3-业务线/Gitea知识库/` | confirmed |
|
||
| D02 | 业务责任人 | Verlit | confirmed |
|
||
| D06 | discussion 发布 | publisher 明确发布；不进入内容审核 | confirmed |
|
||
| D07 | confirmed/internal | 按项目审核策略；试点 `forced_off` | confirmed |
|
||
| D08 | 审核策略 | 试点 `forced_off`；只模拟 ON 负面测试 | confirmed |
|
||
| D09 | AI 默认等级 | A1/A2 默认；A3/A4 只能通过用户绑定 MCP、精确确认和发布网关受控执行 | confirmed-v1.1 |
|
||
| D10 | AI 提交发布 | Agent 可代表已登录且已授权用户提交 discussion/confirmed 请求；不得直接 Git 写入 | confirmed-v1.1 |
|
||
| D11 | MCP 首期范围 | MCP 是唯一用户业务入口；生产目标远程 MCP，STDIO 仅限本地开发 | confirmed-v1.1 |
|
||
| D13 | current 入口 | 用户和 Agent 经 Context Reader MCP 访问；底层保持项目级只读端口 | confirmed-v1.1 |
|
||
| D14 | 试点敏感等级 | 只允许 `internal` | confirmed |
|
||
| D17 | 自定义业务 Web | 不建设登录页、驾驶舱、权限后台或审计后台；Agent Host 承担交互 | confirmed-v1.1 |
|
||
| D18 | 身份与权限 | 飞书登录绑定内部稳定用户及 Gitea 账户；内部 ProjectGrant＋Gitea 权限双层限制 | confirmed-v1.1 |
|
||
| D19 | 强制审计 | 每次 MCP 调用由服务端自动记录 human＋agent＋service；查询可走 MCP，写入/删除不暴露 | confirmed-v1.1 |
|
||
|
||
## 3. 未来 G0 实施准入必须确认的参数
|
||
|
||
本节只在 Verlit 明确宣布进入真实实施后启用；当前 open 状态不阻断工程设计构建。
|
||
|
||
| ID | 参数 | 当前状态 | 推荐与约束 | 阻断的后续任务 |
|
||
|---|---|---|---|---|
|
||
| D03 | 首个试点项目 | open | 1 个正在运行、低敏感、Markdown 为主、确有多人共享需求的项目 | EXE-02～12 |
|
||
| D04 | 项目成员 | open | 从真实参与者中选择 3～4 人，不默认全员授权 | EXE-03/04/12 |
|
||
| D05 | 人员角色 | partial | 业务责任人、项目维护者、至少 1 名 publisher；治理管理员为 Verlit；试点 reviewer 为空 | EXE-04/07/12 |
|
||
| D12 | 目标服务器 | open | 明确稳定标识、用途、OS、网络、管理员和维护窗口；不能凭 IP 猜测 | EXE-03/11 |
|
||
| D15 | RPO/RTO | open | 试点建议 RPO≤24h、RTO≤4h | EXE-03/11/12 |
|
||
| D16 | 紧急责任人 | open | 平台、业务、安全、备份至少各有责任角色，小团队可兼任 | EXE-11/12 |
|
||
|
||
## 4. 未来开发与实施技术参数
|
||
|
||
以下参数在对应代码开发或实施任务开始前确认，不要求现在回答，也不要求全部在 G0 一次回答。
|
||
|
||
### 4.1 稳定标识与契约
|
||
|
||
| 参数 | 推荐 | 当前状态 |
|
||
|---|---|---|
|
||
| `business_line_id` | 使用稳定机器 ID，显示名仍为“Gitea知识库” | open |
|
||
| `project_id` | 小写、稳定、不可复用，不使用“测试/临时”作为业务含义 | blocked-by-D03 |
|
||
| `artifact_id` | 业务可读稳定 ID；创建后不随标题改名 | open |
|
||
| ID namespace | `human:`、`agent:`、`service:`、`project:`、`artifact:`、`release:` | fixed |
|
||
| 时间格式 | RFC3339，包含时区 | fixed |
|
||
| hash | UTF-8 规范化内容 SHA-256，并声明 scope | fixed |
|
||
| schema 版本 | v1.0 发布契约基线＋v1.1 身份/MCP/审计契约；minor 兼容新增，major 改语义 | fixed |
|
||
|
||
### 4.2 来源与构建
|
||
|
||
| 参数 | 推荐 | 当前状态 |
|
||
|---|---|---|
|
||
| v1 来源 | 本地 Markdown | fixed |
|
||
| 选择粒度 | 整文件＋标题章节；自由片段后置 | recommended-pending |
|
||
| 未发布链接 | 默认 block；允许显式缺口需单独决定 | open |
|
||
| 附件类型和大小 | 使用 allowlist，未知二进制和压缩包 block | open |
|
||
| 临时构建区 | vault 外；失败默认清理，仅保留脱敏摘要 | recommended-pending |
|
||
| 飞书/Notion/数据库内容来源 | v1.2 或以后；v1.1 只使用飞书身份 | out-of-v1.1 |
|
||
|
||
### 4.3 Gitea 与基础设施
|
||
|
||
| 参数 | 推荐 | 当前状态 |
|
||
|---|---|---|
|
||
| 部署方式 | 只读盘点后在 Docker/原生服务间选择，固定版本 | blocked-by-D12 |
|
||
| 数据库 | 依据目标环境、备份和恢复能力决定 | blocked-by-D12 |
|
||
| 域名与 HTTPS | 内网 HTTPS，管理入口限制可信网络 | blocked-by-D12 |
|
||
| 公网访问 | v1 默认不需要 | recommended-pending |
|
||
| NAS 路径 | 需要真实路径、认证、带宽和恢复验证 | blocked-by-D12 |
|
||
| 分支保护 | 普通成员不能写 `main`；网关服务身份唯一写入 | fixed |
|
||
| 审核控制面 | 受保护 governance 分支或独立配置存储 | implementation-choice |
|
||
|
||
### 4.4 current 与读取
|
||
|
||
| 参数 | 推荐 | 当前状态 |
|
||
|---|---|---|
|
||
| 读取形式 | 用户侧固定为远程 MCP；服务内部 read port 的具体传输待选 | open-for-C1 |
|
||
| 项目隔离 | 独立路径/域名和认证 scope | fixed |
|
||
| 原子切换 | 不可变 release 目录＋原子 current 指针 | fixed |
|
||
| release 保留 | 至少保留上一版快速回切，数量按磁盘和审计确认 | open |
|
||
| 缓存 | 键包含 release/hash，禁止新旧混合 | fixed |
|
||
| discussion 默认搜索 | 允许读取但显著标注；是否默认检索待确认 | open |
|
||
|
||
### 4.5 安全、运维与事故
|
||
|
||
| 参数 | 推荐 | 当前状态 |
|
||
|---|---|---|
|
||
| prohibited | token、私钥、cookie、明文敏感个人信息、控制文件 | fixed |
|
||
| restricted | 不进入 v1 试点 | fixed |
|
||
| PII 规则 | 由安全/业务责任人确认具体口径 | open |
|
||
| 扫描例外批准人 | 非 Agent，绑定 finding/hash/有效期 | open |
|
||
| 日志保留 | 正文和秘密最小化，期限待确认 | open |
|
||
| 告警渠道 | 必须有 owner、确认、升级和关闭记录 | open |
|
||
| 恢复演练 | 首次试点前一次；建议后续每季度 | recommended-pending |
|
||
|
||
### 4.6 MCP、身份与审计
|
||
|
||
| 参数 | 推荐与约束 | 当前状态 |
|
||
|---|---|---|
|
||
| Agent Host | Agent 无关兼容框架，优先适配 Codex、Claude Code；支持逐用户远程 MCP OAuth、框架确认和受控本地文件传输 | architecture-confirmed；版本待 C1-00 |
|
||
| 运行时与语言 | 推荐 Go 1.26.x 最新安全补丁；若团队不能维护 Go，必须在 C1-01 前重新选型 | recommended-pending-C1 |
|
||
| MCP SDK/协议 | 推荐官方 Go SDK v1.7.x；目标 `2026-07-28`，兼容协商 `2025-11-25` | recommended-pending-host-test |
|
||
| 生产传输 | 远程 Streamable HTTP MCP；认证绑定 resource/audience/client/subject | recommended-pending-host-test |
|
||
| 本地开发传输 | STDIO，可使用合成身份；不得变成生产共享入口 | recommended-pending |
|
||
| OAuth 授权服务器 | 使用成熟 OAuth/OIDC Authorization Server 承担 PRM、PKCE、resource/audience、客户端和令牌生命周期；不得在 `contextd` 内从零自研完整授权服务器 | open-for-C1-04 |
|
||
| 飞书登录集成 | 飞书作为员工身份联邦来源，不把飞书 token 透传到 MCP resource server 或 Gitea | open-for-C1 |
|
||
| 身份权限数据库 | 推荐 PostgreSQL 18.x＋pgx/sqlc；保存内部用户、绑定、ProjectGrant、会话和版本 | recommended-pending-environment |
|
||
| 飞书—Gitea 绑定 | 首期受控预配置 `tenant_key＋飞书稳定 ID ↔ Gitea numeric ID`；未绑定即拒绝，不信任自报 username | fixed-flow；名单/责任人待 G2 |
|
||
| Gitea 权限复核 | 每次项目访问实时 API 复核，首期 allow cache 关闭，故障 fail closed；具体 API/凭据待 G0 | architecture-confirmed |
|
||
| Local Source Gate | 默认 Markdown 2 MiB/文件、受控附件 5 MiB/文件、bundle 10 MiB/100 文件、256 KiB chunk；允许根、secret/PII 策略待 C1-08 确认 | defaults-proposed |
|
||
| 中文搜索 | PostgreSQL `pg_trgm`＋标题/标签/路径/正文过滤，仅索引 current；真实规模基准不达标才评审其他方案 | recommended-pending-benchmark |
|
||
| Audit Store | 推荐 PostgreSQL 独立 schema/角色＋outbox＋append-only event；保留期限待定 | recommended-pending-policy |
|
||
| 会话与 token | 短期、不可转交；issuer/audience/resource/expiry/client/subject/scope 全部验证 | open-for-C1 |
|
||
| 审计脱敏 | 不记录正文、原始 Prompt、token、cookie、私钥和完整敏感参数 | fixed-v1.1 |
|
||
| 运维入口 | 部署、迁移、备份、密钥和 Gitea Admin 不作为普通 MCP 工具 | fixed-v1.1 |
|
||
|
||
## 5. 可选、关闭或后续版本决定
|
||
|
||
| ID | 决定 | 推荐 | 状态 |
|
||
|---|---|---|---|
|
||
| O01 | 发布驾驶舱/自定义 Web | v1.1 明确不建设 | closed-v1.1 |
|
||
| O02 | Context Reader MCP | 已提升为 v1.1 必需能力 | promoted-v1.1 |
|
||
| O03 | Publish Gateway MCP | 已提升为 v1.1 必需能力，仍只提交受控请求 | promoted-v1.1 |
|
||
| O04 | 飞书通知 | 人工发送回执即可完成 v1 | deferred |
|
||
| O05 | 正式审批 | 由试点真实摩擦决定 | v2-candidate |
|
||
| O06 | 飞书身份与权限数据库 | 已提升为 v1.1 必需能力 | promoted-v1.1 |
|
||
| O07 | Skill Registry | 与普通 Context 分离，独立版本评审 | v1.2-candidate |
|
||
|
||
O02、O03、O06 已经成为当前 v1.1 目标，不再允许实现时按“可选”省略。O01 只有重新立项并改变 v1.1 产品入口时才可打开。
|
||
|
||
## 6. 未来 G0 实施准入完成检查
|
||
|
||
- [x] 正式业务线和责任人明确。
|
||
- [x] v1 主方案和真源优先级明确。
|
||
- [x] v1.1 差量覆盖层和版本应用顺序明确。
|
||
- [x] v1 冻结原则和禁止偏移项明确。
|
||
- [ ] D03 首个试点项目已确认。
|
||
- [ ] D04 项目成员已确认。
|
||
- [ ] D05 维护者和 publisher 已确认。
|
||
- [ ] D12 目标服务器和管理员已确认。
|
||
- [ ] D15 RPO/RTO 已确认。
|
||
- [ ] D16 紧急责任角色已确认。
|
||
- [ ] `business_line_id`、`project_id` 和首批 `artifact_id` 规则已确认。
|
||
- [ ] 实施前风险、停止条件、回滚和验收负责人已确认。
|
||
- [ ] Agent Host、飞书登录应用/身份代理和真实用户范围已确认。
|
||
- [ ] 远程 MCP 地址、认证方式、协议/SDK版本和 token 生命周期已确认。
|
||
- [ ] 身份权限数据库、audit store、保留期限和安全责任人已确认。
|
||
- [ ] Gitea 账户绑定、权限复核、缓存失效和撤权验证方式已确认。
|
||
|
||
上述未完成项不会阻断当前本地工程设计。只有 Verlit 明确宣布进入真实实施时，它们才成为准入门；补齐前不得执行服务器连接、部署、远端仓库创建、账号和权限写入。代码开发另走 `C1 代码开发准入`，不自动获得任何真实环境权限。
|