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:305fe209cfd7c6485f36a48b3e952b19a0da02bcd4392e1b148b4121a6c519fc	Markdown 正文（从一级标题开始至文件末尾）的 UTF-8 SHA-256	3-业务线/Gitea知识库/_context		3-业务线/Gitea知识库/公司共享 Context 项目仓库发布方案 v1 3-业务线/Gitea知识库/公司共享 Context MCP-first 身份与审计方案 v1.1 3-业务线/Gitea知识库/v1-设计追溯与版本关系 0-收集箱/临时待归属/2026-08-03-公司共享Context发布与AI协同框架/2026-08-03-执行落地手册/

Gitea知识库 v1.1 详细实施方案

1. 文档定位

本方案把已冻结的 v1 基线和 v1.1 MCP-first 身份与审计覆盖层转换为可下发、可验收、可停止和可回滚的执行顺序。它不替代两份设计真源，也不引入 Skill Registry、飞书内容来源、通用审批、自定义业务 Web 或其他后续版本能力。

当前尚未确认试点项目、人员和服务器，因此本文只固定与环境无关的动作、产物和验收门。具体操作系统命令、端口、域名、目录、数据库和服务版本必须在 EXE-03 只读盘点后补齐；在目标未知时编写假命令不视为实施方案完成。

2. v1.1 完成定义

v1 完成不是“Gitea 已安装”，而是一个真实低敏感项目完成以下闭环：

明确选择本地 Markdown
  → 确定性构建
  → 质量与安全检查
  → 发布请求与 CAS
  → 发布网关写入受保护 main/current
  → 原子导出唯一 current
  → 飞书登录绑定内部用户并通过双层权限
  → Agent 只经 MCP 读取/构建/受控提交
  → 人和 Agent 读取同一 release/hash/status
  → 每次调用的 human＋agent＋service 审计、回执、备份、撤权和恢复均可验证

3. 不可变实施边界

• 一项目一私有仓库；仓库是最小权限边界。
• 个人工作区到公司仓库是单向明确发布，不做同步和自动反向回写。
• 只有发布网关服务身份可以写 main。
• main/current 是唯一默认读取面，Git 历史和构建区不进入 Agent 默认 Context。
• discussion/confirmed 是内容状态；pending_review 等只属于 release 事务。
• 试点 review_mode=forced_off；仅在测试环境模拟审核 ON 的负面路径。
• Agent 默认 A1/A2；A3/A4 只可代表已登录用户经 MCP、精确确认和发布网关受控执行，不持有 Git、SSH、管理员或审核策略写凭据。
• 远程 MCP、飞书登录绑定、内部权限数据库、Gitea 权限复核和强制审计属于 v1.1 必需链路。
• 飞书内容来源、Skill Registry、正式审批和自定义业务 Web 页面不属于 v1.1。

4. 总体依赖与批次

flowchart LR
  E01[EXE-01 试点与责任] --> E02[EXE-02 契约]
  E01 --> E03[EXE-03 Gitea基础层]
  E01 --> E04[EXE-04 身份权限]
  E02 --> E05[EXE-05 来源构建]
  E05 --> E06[EXE-06 安全检查]
  E02 --> E07[EXE-07 发布网关]
  E03 --> E07
  E04 --> E07
  E06 --> E07
  E07 --> E08[EXE-08 current导出]
  E04 --> E09[EXE-09 MCP Gateway]
  E07 --> E09
  E08 --> E09
  E09 --> E10[EXE-10 Agent与读回]
  E03 --> E11[EXE-11 运维保障]
  E08 --> E11
  E10 --> E12[EXE-12 真实试点]
  E11 --> E12

批次 A：本地准备

EXE-01 剩余决策、EXE-02 契约清单、EXE-04 身份/角色/权限矩阵、EXE-09 MCP 工具清单、风险和验收计划。不得连接服务器或创建远端资源。

批次 B：基础设施与本地代码

Gate 0 通过后，EXE-03 的测试环境 Gitea、EXE-02 契约代码、EXE-05 构建器和 EXE-06 检查器可以按依赖并行推进。

批次 C：发布闭环

EXE-07 网关、EXE-08 current、EXE-09 MCP Gateway、EXE-10 Agent 与读回串行收敛；MCP 不再是可选适配层。

批次 D：运维与真实试点

EXE-11 在基础设施阶段开始，真实试点前完成；EXE-12 只在全部适用门禁通过后启动。

5. EXE-01——试点、责任与执行边界

v1 依据：主方案十一、十二、十五；详细方案 Gate 0。

前置：业务线和 owner 已确认。

执行步骤：

1. 从实际业务项目中选择一个低敏感、Markdown 为主、确实需要多人共享 Context 的候选。
2. 固定稳定 project_id、业务目标、允许内容和明确禁止内容。
3. 确定 3～4 名真实成员，不默认全员授权。
4. 指定业务责任人、项目维护者、至少一名 publisher；Verlit 为治理管理员，试点 reviewer 为空。
5. 指定平台、安全和备份责任角色，可兼任但不能无人负责。
6. 确认目标服务器、管理员、网络、域名、磁盘和 NAS 候选。
7. 确认产物进入本业务线、未来正式代码库和 _runtime/context-publish/ 证据区。
8. 复核 v1 禁止项并由责任人确认不扩大范围。

交付物：试点登记、人员角色矩阵、允许/禁止内容清单、目标资源清单、责任与验收人。

验收门：业务目的、项目、成员、角色、服务器候选、敏感级别和成功标准均明确。

停止条件：只有“搭系统”而无真实项目；责任人缺失；使用测试/临时作为项目业务目的；希望直接部署但不确认权限、备份和沉淀位置。

6. EXE-02——接口契约与状态机

v1 依据：主方案五～九；详细设计 04、07、11。

前置：EXE-01 完成；正式代码库和稳定 ID 规则明确。

执行步骤：

1. 在正式代码库建立 contracts/、examples/valid/、examples/invalid/ 和 tests/。
2. 固定 selection、artifact、validation、review policy/decision、release request、current manifest、readback 和错误对象 schema v1.0。
3. 叠加 UserIdentity、Feishu/Gitea Binding、ProjectGrant、AgentSession、MCP Tool 和三主体 Audit Event schema v1.1。
4. 固定 human/agent/service 等 namespace、RFC3339 时间、SHA-256 规范化算法和 hash scope。
5. 固定 discussion/confirmed、敏感等级、发布状态和异常状态枚举。
6. 把 review decision、validation exception、operation authorization 分为三个契约。
7. 每类契约至少建立一个有效和两个无效样例。
8. 实现必填字段、未知 major、hash 篡改、身份冒充、秘密字段和策略覆盖负面测试。
9. 验证 forced_off confirmed 不需要 review decision；模拟 ON 时决定必须绑定完整 candidate hash。

交付物：版本化 schema、样例、状态机、错误码和统一测试入口。

验收门：所有模块能一致解析同一示例包；无效样例按预期失败；payload 不能覆盖服务端审核策略。

回滚/停止：字段语义不一致、全部字段被做成可选、日志会写入秘密或无法定义规范化 hash 时停止，不进入编码下游。

7. EXE-03——服务器盘点与 Gitea 基础层

v1 依据：主方案十、十一、十二；详细设计 10。

前置：EXE-01 指定目标服务器、管理员、备份目标和维护窗口；另行通过远端执行门禁。

执行步骤：

1. 用具名只读身份确认服务器稳定标识、用途和负责人，禁止凭 IP 猜测。
2. 盘点 OS、CPU、内存、磁盘、文件系统、容器运行时、现有端口、反向代理、数据库、DNS、证书、防火墙、监控和 NAS 路径。
3. 检查是否已有 Gitea/Git 服务及未知生产配置。
4. 形成部署拓扑、版本、数据路径、端口、HTTPS、数据库、升级、备份和回滚方案。
5. 获得具体写入授权后，先备份目标目录和反向代理配置。
6. 使用版本化配置部署固定版本 Gitea 和数据库；不使用浮动 latest。
7. 禁止公开注册，隔离管理员与普通账号，限制管理入口。
8. 创建一个试点私仓、独立测试账号和受保护 main；治理配置使用独立保护控制面。
9. 建立仓库、数据库、配置和应用版本的异机备份。
10. 在隔离环境恢复一次，验证用户、团队、仓库、分支保护和 commit。

交付物：盘点报告、部署配置仓库、Gitea 环境、试点私仓、备份与恢复证据。

验收门：HTTPS、禁止公开注册、授权与未授权测试、普通成员不能 push main、服务重启完整、异机恢复成功。

回滚/停止：目标不明、覆盖未知生产配置、没有备份/恢复或只能共享管理员账号时停止；部署失败按版本化配置和前置备份回滚。

8. EXE-04——身份、角色、权限和凭据

v1/v1.1 依据：主方案四；v1.1 身份模型、双层权限和 AgentSession。

前置：EXE-01 人员角色；账号创建等待 EXE-03。

执行步骤：

1. 完成人员—项目—角色—MCP action 矩阵，记录兼任关系和明确禁止能力。
2. 建立内部稳定 UserIdentity，用飞书 tenant_key/open_id 绑定用户；不保存飞书 token 明文。
3. 将内部用户绑定独立 Gitea 账户；不共享账号、key 或长期 token。
4. 建立 ProjectGrant 第一层权限和 Gitea 项目成员/读取资格第二层复核；任一层拒绝均 fail closed。
5. 建立短期 AgentSession，绑定 user、agent、client、scope 和 expiry；工具参数中的用户、角色、grant 不具权威性。
6. 固定业务责任人、维护者、作者、publisher、成员、治理管理员和平台/安全角色。
7. 建立 mcp-gateway、publish-gateway、current-exporter、context-reader、audit-writer、backup-service 和 monitoring-service 项目级身份。
8. 按 dev/test/prod 分离身份和凭据；读、发布、管理、审计、备份、恢复凭据分离。
9. Agent A1/A2 默认；A3/A4 必须绑定精确确认后由网关执行；A5 禁止。
10. 秘密进入密钥系统，只在文档记录非敏感引用、owner、scope、期限和轮换时间。
11. 对每个角色执行授权/未授权、身份冒充和双层权限不一致测试，并演练成员移除、绑定失效、凭据吊销和 Agent 停用。

交付物：身份绑定模型、双层授权矩阵、服务身份清单、Agent 工具白名单、凭据引用登记、撤权与 break-glass 指南。

验收门：任一权限能解释允许原因；移除成员后仓库、current 和工具未来访问均拒绝；Agent 无法自授或切换高权限身份。

停止条件：需要共享账号、万能 token、向模型暴露秘密，或平台管理员自动拥有全部业务内容时停止。

9. EXE-05——来源选择器与确定性构建器

v1 依据：主方案三、六、十三；详细设计 03、11。

前置：EXE-01、02；正式代码库和 v1.0 schema。

执行步骤：

1. 第一版只支持本地 Markdown，不接飞书、Notion 和数据库。
2. 接受明确的 business line、project、artifact、来源路径、文件/章节选择、排除项和敏感级别。
3. 解析真实路径并确保位于 allowlist 根目录；拒绝 .git、子仓库、隐藏配置、凭据和控制文件。
4. 保存来源版本/hash；构建前再次校验，变化时返回 SOURCE_CHANGED。
5. 在 vault 外临时目录按 selection 读取，不递归扫描未选择目录。
6. 规范 UTF-8、换行、标题和相对路径；收集允许附件并改写项目链接。
7. 未发布链接按已确认策略 block 或显式标记，不能伪装可访问。
8. 生成 artifact manifest、checksums、构建摘要和可重复构建验证。
9. 成功或失败后清理临时目录；仅按策略保留脱敏摘要。

交付物：selector、builder、内部服务端口、fixtures 和自动测试；用户侧工具由 EXE-09 暴露。

验收门：同样输入产生同样 hash；未选内容、私人路径、历史、子仓库和控制文件不可检索或被拒绝。

停止条件：实现要求扫描整个私人空间、构建器直接写 Gitea/current、或临时目录进入 Agent 默认读取面时停止。

10. EXE-06——质量与安全检查门

v1 依据：主方案六、十一、十三；详细设计 09。

前置：EXE-02 schema、EXE-05 artifact bundle、策略责任人。

执行步骤：

1. 建立版本化 policy bundle、allowlist、禁止路径、secret/PII、链接和控制文件规则。
2. 按固定顺序执行 schema/hash、文件、路径、secret、PII、链接、控制文件、提示注入和附件检查。
3. 结果仅使用 pass、warning、block、error；scanner error 按 block。
4. 默认阻断 secret、个人敏感信息、路径逃逸、未知二进制、控制文件、跨项目内容和 checksum 不一致。
5. 例外必须绑定 finding、artifact hash、规则、范围、批准人和过期时间；内容变化后失效。
6. secret、私钥和路径逃逸不允许普通豁免。
7. 输出符合 schema 的 validation report，记录策略和扫描器版本。
8. 使用攻击语料验证提示注入、压缩包、符号链接、外部恶意链接和扫描器故障。

交付物：policy bundle、检查器、validation report、攻击语料和自动测试。

验收门：全部阻断语料被拦截；error 不变 pass；报告 hash 和策略版本可验证；检查器没有远端写权限。

停止条件：完整私密内容需要发送到未批准外部服务、AI 能修改策略/批准例外、或超时被视为通过时停止。

11. EXE-07——发布网关与事务控制

v1 依据：主方案六～九；详细设计 04、11 和审核治理基线。

前置：EXE-02、03、04、06 全部通过。

执行步骤：

1. 实现 release validate/create/status/cancel 和独立 review policy 接口。
2. 只从 MCP 验证上下文取得 human/agent/session，并验证业务线、项目、双层权限、content status、artifact 和 validation hash；拒绝 payload 自报身份。
3. 接受请求时从保护控制面快照审核策略；客户端不得覆盖策略。
4. discussion 或 OFF confirmed 直接进入提交链；模拟 ON 时整个 confirmed candidate 等待精确 hash 审核。
5. 实现幂等键、冲突检测、单向状态转换和服务重启恢复。
6. 提交前重新读取 Gitea main，与 base_current 做 CAS；不一致返回 STALE_BASE。
7. 在临时工作区生成完整新 current，使用项目级网关凭据写入受保护 main。
8. 记录 commit、release manifest、before/after、actor 和 correlation ID。
9. 触发 EXE-08 并等待导出和读回；Git 成功不得提前报告 completed。

交付物：网关、状态存储、策略控制、Gitea 项目写入、内部端口和正反测试；用户侧不另建 REST/CLI 入口。

验收门：旧基线不能覆盖新 current；重复请求只有一个逻辑发布；普通成员/Agent 无法绕过；OFF/模拟 ON 行为正确。

回滚/停止：无法保护 main、无法可靠幂等、网关需要读取私人来源或写入后无法查询导出状态时停止。

12. EXE-08——current 导出与只读入口

v1 依据：主方案三、五、六、八、九。

前置：EXE-03、EXE-07。

执行步骤：

1. 只接受网关状态为 committed 的 project/release/commit 和期望 manifest hash。
2. 使用只读 Gitea 身份取得指定 commit，不以移动的 main 作为隐式输入。
3. 在不可变 releases/<release-id>/ staging 中展开仓库 current/。
4. 拒绝 .git、schema、历史、构建区和未允许路径进入读取根。
5. 校验 _release.yaml、文件清单、checksums、owner 和目录权限。
6. 本地自检通过后用原子 rename/symlink 切换 current，保留上一版回切点。
7. 提供项目级内部只读端口，设置认证 scope 和 release/hash 缓存键；用户侧读取只经 EXE-09 MCP 工具。
8. 切换失败验证旧 current 未变；切换后自检失败按策略回切并告警。

交付物：导出器、不可变 release 目录、唯一 current、机器 manifest 入口和回切机制。

验收门：并发读取只看到完整旧版或新版；未授权访问不能枚举其他项目和历史；pending/rejected 不产生可读 release。

13. EXE-09——MCP Gateway、用户绑定与工具门禁（必需）

v1/v1.1 依据：v1 发布/读取边界；v1.1 MCP 工具面、身份、双层权限和强制审计。

前置：EXE-04 身份与授权、EXE-07 发布网关、EXE-08 内部读取端口完成；Agent Host 与飞书登录集成方式已确认。

执行步骤：

1. 固定 MCP SDK、最低协议版本、生产远程 transport 和本地 STDIO 开发方式。
2. MCP 连接验证 issuer、audience、resource、expiry、client、subject 和 scope，并解析内部 user/AgentSession；不信任工具参数中的身份。
3. 注册身份/项目、current 读取/搜索、构建/验证/diff、发布请求/状态/取消和审计查询工具。
4. 每个工具在业务执行前完成业务线、project、action、resource、内部 ProjectGrant、Gitea 权限和精确确认判断。
5. A3/A4 只提交发布网关请求，不持有 Git 凭据；远端写仍由项目级网关服务身份完成。
6. 在统一中间件自动写 request、allowed/denied、completed/failed 三主体审计；不暴露普通审计写入/删除工具。
7. 明确排除 Gitea Admin/直接 push、SSH、任意 SQL、部署、迁移、备份、密钥、权限写入和动作开关工具。
8. 不建设自定义登录页、驾驶舱、权限后台和审计后台；Agent Host 是交互界面。
9. 测试未归属、身份冒充、跨项目、权限不一致、A1 调发布、提示注入、参数逃逸、审计中断和故障降级。

验收门：两名飞书用户的主体、项目和权限正确分离；每次调用有 human＋agent＋service 审计；停用 MCP 不回退到 shell/API/共享账号；未授权请求在服务端失败。

停止条件：只能使用共享机器人主体、需要全局管理员 token、权限只存在 prompt、客户端可自报用户、审计可选或只读工具可逃逸写入时停止。

14. EXE-10——Agent 读取、读回与人机协同

v1 依据：主方案三、四、八、十一；详细设计 08。

前置：EXE-08 提供项目级内部读取端口；EXE-09 提供用户绑定 MCP 工具面。

执行步骤：

1. 分离 Business Router、Context Reader、Context Builder、Policy Checker、Release Coordinator 和 Audit Assistant 配置。
2. 固定每个角色的项目、工具白名单、最大动作等级、输入来源和 human＋agent＋service 审计字段。
3. 先按业务线和 project 路由，不扫描全部仓库。
4. Agent 只经 MCP 从授权入口读取 current manifest，仅读取 manifest 列出的 artifact。
5. 回答携带 project、release、artifact、status 和 hash；discussion 显著标注。
6. 对冲突 confirmed 停止自动业务行动并展示来源。
7. 发布后从正式入口重新读取，不使用构建缓存；比对 release、commit、manifest hash、artifact 状态和关键结论。
8. 验证未授权项目、历史和控制面不可读；恶意正文不能改变工具权限、用户身份或确认内容。
9. 验证 A3/A4 产生精确确认引用，commit 同时可追溯 human、agent 和实际网关服务身份。
10. 只有 readback pass 且强制审计已持久化才允许发布事务 completed。

交付物：Agent 角色配置、读取规范、readback report、提示注入和权限负面测试。

验收门：Agent 始终返回正确版本和状态；A2 无远端写能力；A3/A4 不能绕过精确确认和网关；未授权项目不可搜索、读取或枚举。

15. EXE-11——监控、审计、备份与事故响应

v1 依据：主方案九～十二；详细设计 09、10。

前置：随 EXE-03 开始，EXE-08/10 后收口。

执行步骤：

1. 为 identity、permission、MCP、build、validation、gateway、Gitea、export、readback 和 audit store 定义健康检查。
2. 每次 MCP 调用自动记录 correlation、session、tool、action、human、agent、service、authorization、confirmation、stage、result 和远端版本。
3. 监控失败阶段、耗时、stale base、幂等、Git/current/readback 不一致、越权、撤权延迟、磁盘、证书和备份年龄。
4. 分开审计 review decision、validation exception 和 operation authorization；审计查询可走授权 MCP，写入/修改/删除不开放。
5. 日志只保存脱敏摘要/hash，不记录正文、token、cookie、私钥和非必要个人信息。
6. 备份 Gitea 仓库、数据库、配置、权限、分支保护、网关状态、导出配置和治理控制面。
7. 密钥由独立密钥系统备份或重建，普通备份不含明文秘密。
8. 使用 outbox/等价机制验证动作和事件关联；写操作审计失败时 fail closed，读取审计队列不可用时同样拒绝。
9. 完成 artifact 恢复、导出节点恢复、Gitea 恢复、身份权限库/audit store 恢复、整机隔离恢复和凭据轮换演练。
10. 编写并演练 S2 错误内容、S3 越权/敏感 current、S4 凭据/PII 进入历史剧本。

交付物：指标、告警、审计、备份计划、恢复记录、事故手册和责任表。

验收门：任一失败可定位；告警可送达并关闭；空环境恢复后人和 Agent 读取一致；旧身份和凭据失效。

停止条件：备份从未恢复、日志含秘密、事故临时找责任人或不可观测状态仍允许高风险发布时停止。

16. EXE-12——真实试点与 v2 判决

v1 依据：主方案十一、十二；详细设计 12。

前置：EXE-01～11 中适用门禁通过，备份恢复和事故联系人就绪。

执行步骤：

1. 复核只有一个 internal 真实项目、角色清楚、forced_off 和停止条件已通知。
2. 运行原 12 类规定样本，并增加飞书用户区分、参数冒充、双层权限不一致、逐调用三主体审计、审计中断和无高权回退样本。
3. 完成至少两轮真实发布，不以人工样本或安装完成代替使用。
4. 至少两名非平台维护者参与选择、发布或纠错。
5. 记录人工步骤、耗时、失败、困惑、Agent 引用和纠错成本。
6. 汇总 Git/current/readback、越权、安全、撤权、告警、恢复和成员反馈证据。
7. 命中止损条件时停止扩项目，决定修复、降级或终止。
8. 只根据真实摩擦决定保持 v1.1、增加 Skill Registry、飞书内容来源、审批/跨项目能力或回退简化。

交付物：M01～M10、T01～T12 样本记录、真实发布回执、指标、缺陷、恢复证据、成员反馈和后续版本决定。

通过门：一致率 100%；用户业务 MCP 审计覆盖率 100%；未授权成功、共享主体、私人泄露和控制面被覆盖为 0；discussion 不被冒充 confirmed；撤权、恢复和告警有效；收益高于维护成本。

17. 任务下发与证据

每个 EXE 任务进入 in_progress 前必须形成任务单，至少包含：

• 业务线、项目、目标资源和产物位置；
• 主责任人、协作人、验收人、安全/平台联系人；
• 要做、不做、允许工具和禁止动作；
• Business Gate、动作门禁、身份、precheck、备份和回滚；
• 逐项动作、验收、停止条件和证据位置。

运行证据建议进入：

_runtime/context-publish/<correlation-id>/
├─ request.yaml
├─ precheck.yaml
├─ inputs/
├─ payload/
├─ outputs/
├─ postcheck.yaml
├─ audit-events.ndjson
└─ result.yaml

该路径只在具体执行任务通过门禁后创建；阶段 0 不提前写入运行证据。

18. 当前可执行范围

本文全部 EXE 内容是未来真实实施蓝图，不是当前待运行任务。当前 C0 工程设计构建 只允许维护 v1/v1.1 设计追溯、工程构建规格、开发任务分解、契约逻辑、测试规格、风险和验收清单。

当前不可执行：平台代码仓库创建、系统代码编写或运行、服务器连接、Gitea 部署、账号和权限写入、远端仓库创建、密钥生成、发布和 _runtime 执行证据写入。

进入代码开发必须先通过 C1 代码开发准入；进入本方案 EXE-01～12 的真实实施必须再由 Verlit 明确授权，并通过 G0 实施准入。两类授权均不会自动发生。