commit cabe98207c45789ea9425a4de20bf3f78a82f3d1 Author: verlit Date: Tue Aug 11 15:40:11 2026 +0800 提交gitea知识库方案 diff --git a/Gitea知识库/Gitea知识库 v1.1 产品需求文档 PRD.md b/Gitea知识库/Gitea知识库 v1.1 产品需求文档 PRD.md new file mode 100644 index 0000000..9bc9a2e --- /dev/null +++ b/Gitea知识库/Gitea知识库 v1.1 产品需求文档 PRD.md @@ -0,0 +1,435 @@ +--- +title: Gitea知识库 v1.1 产品需求文档 PRD +date: 2026-08-10 +type: PRD +status: review-ready +content_status: discussion +owner: Verlit +last_updated_at: 2026-08-10 +last_updated_by: Codex +hash: sha256:f2abc96b306a2314d8abf6beef982b56a6bd5dd2147bee1adbc025305d0c9536 +hash_scope: Markdown 正文（从一级标题开始至文件末尾）的 UTF-8 SHA-256 +belongs_to: + - "[[3-业务线/Gitea知识库/_context|Gitea知识库]]" +depends_knowledge: + - "[[3-业务线/Gitea知识库/公司共享 Context 项目仓库发布方案 v1|公司共享 Context 项目仓库发布方案 v1]]" + - "[[3-业务线/Gitea知识库/公司共享 Context MCP-first 身份与审计方案 v1.1|公司共享 Context MCP-first 身份与审计方案 v1.1]]" + - "[[3-业务线/Gitea知识库/v1.1-技术栈与详细实施设计|v1.1 技术栈与详细实施设计]]" + - "[[3-业务线/Gitea知识库/v1-验收与止损矩阵|v1.1 验收与止损矩阵]]" +--- + +# Gitea知识库 v1.1 产品需求文档 PRD + +## 1. 文档结论 + +本 PRD 已具备进入 C1 代码开发评审的业务与工程完整度，但不代表已经授权开发、部署或连接真实环境。当前仍处于 `C0 本地工程设计构建`；下一阶段必须由 Verlit 明确宣布后才开始。 + +方案没有方向性缺陷，也没有偏离原 v1。原 v1 的“一项目一私仓、单向明确发布、发布网关唯一写 `main`、不可变 release、唯一 `main/current`、内容状态与事务状态分离、可恢复和可止损”保持不变；v1.1 只补充 MCP 唯一用户入口、飞书身份、内部权限数据库、Gitea 二次复核、受控本地来源、Agent 无关适配和强制审计。 + +本轮闭合了三项此前不够明确的实现问题： + +1. MCP OAuth 由成熟 OAuth/OIDC Authorization Server 承担协议和令牌生命周期，飞书作为员工身份来源；不在业务服务内从零自研完整授权服务器。 +2. 飞书登录不等于 Gitea 授权；v1.1 试点通过受控预配置绑定飞书稳定 ID 与 Gitea 数字用户 ID，未绑定即拒绝。 +3. 中文检索首期采用 PostgreSQL `pg_trgm`＋元数据过滤，不把面向英文分词的原生 FTS 当成中文主检索。 + +仍未确定的内容属于环境和治理参数，见第 17 节；它们不要求重写 PRD，但会在对应阶段形成硬门。 + +## 2. 产品定义 + +### 2.1 产品一句话 + +面向全员 Agent 工作方式，以飞书员工身份登录，通过统一远程 MCP 安全读取和发布项目级共享 Context，并由内部授权与 Gitea 仓库权限共同限制访问，所有人、Agent 和服务行为均可追溯。 + +### 2.2 战略位置 + +本业务线是“企业内部 AI 系统（先知识库、后 Agent）”的共享 Context 与权限治理底座。当前版本先证明知识库内容可被可靠发布、准确读取、即时撤权、完整审计；Skill Registry、正式审批和更多内容来源只在真实试点证明需要后进入后续版本。 + +### 2.3 产品入口 + +- 唯一用户业务入口：Agent Host 中配置的远程 MCP。 +- 首批 Agent adapter：Codex、Claude Code；其他 Agent 只需满足同一 adapter contract。 +- 允许的浏览器页面：飞书/OAuth 授权页及协议回调，不是业务 Web 页面。 +- 不建设：独立企业管理后台、权限页面、发布驾驶舱、审计 Web 页面。 + +## 3. 目标与非目标 + +### 3.1 v1.1 目标 + +- 每位员工使用自己的飞书身份完成 MCP OAuth，不使用共享账号。 +- 通过 `ProjectGrant ∩ Gitea live permission` 实现双层项目权限。 +- Agent 只能读取已授权项目唯一 `current`，不能默认读取 Git 历史、构建区或其他项目。 +- 用户可明确选择本地 Markdown/受控附件，经 Local Source Gate、构建、检查、diff 和一次性确认后发布。 +- `discussion` 和 `confirmed` 复用同一发布链，仅规则和所需权限不同。 +- 每次调用自动记录 human、agent、service 三主体以及请求、授权、结果和关联链。 +- 发布完成以 Git、release、current、检索索引和 MCP readback 一致为准。 +- 支持撤权、失败重试、过期请求、并发冲突和恢复发布。 + +### 3.2 非目标 + +- 不建设自定义业务 Web/移动页面。 +- 不让 Agent、LLM 或用户参数直接决定身份、角色和权限。 +- 不开放任意 SQL、Shell、Git、Gitea Admin、部署、迁移、备份、密钥或审计写删工具。 +- 不接入个人全部工作区，不递归扫描未选择目录。 +- 不在当前版本建设 Skill Registry、skill 审核表或 skill 发布流程。 +- 不做跨项目统一大库、跨项目检索后再由模型过滤。 +- 不把向量库、Elasticsearch、Kafka、Redis、Kubernetes 或微服务作为首期前置。 + +## 4. 角色与责任 + +| 角色 | 说明 | 允许行为 | 禁止行为 | +|---|---|---|---| +| 普通成员 | 已绑定飞书和 Gitea 的项目成员 | 读取、搜索授权项目；提交允许级别的构建请求 | 直接写 Git、修改权限、读取历史或其他项目 | +| Publisher | 获得项目发布动作的成员 | 在检查和确认后提交 discussion/confirmed 发布 | 绕过网关、force push、修改审计 | +| 治理人员 | 维护用户绑定、ProjectGrant、项目配置和例外 | 受控预配置、撤权、审批配置变更 | 通过普通 MCP 自行扩大权限 | +| 审计人员 | 查看授权范围内的脱敏审计 | 查询、追踪、验证事件链 | 修改或删除审计事件 | +| Agent Host | Codex、Claude Code 或兼容 Agent | 调用标准 MCP、展示确认、传递明确选择的内容 | 自报身份、扫描工作区、持有发布 Git 凭据 | +| `contextd serve` | MCP resource server | 身份、授权、工具路由、读、请求入队、审计 | Gitea 写入、迁移、部署 | +| `contextd worker` | 内部可靠任务执行者 | 构建、Git 写入、export、readback | 面向用户开放、Gitea Admin | + +## 5. 系统边界与技术基线 + +```text +飞书用户 + → Codex / Claude Code / Other Agent + → Verlit Agent Compatibility Layer + → OAuth Authorization Server ↔ 飞书 OAuth + → Reverse Proxy → contextd serve (/mcp) + → PostgreSQL Identity/AuthZ/Release/Outbox/Audit/Search + → contextd worker → Gitea 私仓 → immutable release/current + → MCP readback → Agent +``` + +| 能力 | 技术基线 | +|---|---| +| 服务端 | Go 1.26.x，官方 Go MCP SDK v1.7.x，`net/http` | +| MCP | Streamable HTTP；目标 2026-07-28，兼容 2025-11-25 | +| OAuth | 成熟 OAuth/OIDC Authorization Server＋飞书身份联邦；Authorization Code＋PKCE | +| 数据库 | PostgreSQL 18.x，`pgx/v5`、`sqlc`、`goose` | +| 可靠任务 | PostgreSQL transactional outbox，独立 `worker` 运行角色 | +| 仓库 | Gitea 1.26.x 支持分支；每项目一私仓；受保护 `main` | +| Git | 系统 Git CLI、临时 worktree、非 force push、CAS/`base_current` | +| 内容 | `goldmark` AST＋JSON Schema 2020-12＋确定性 builder | +| 中文检索 | PostgreSQL `pg_trgm`＋标题/标签/路径/正文元数据过滤 | +| 审计 | PostgreSQL 独立 schema/角色、append-only、hash chain、每日 checkpoint | +| 观测 | OpenTelemetry；正文、token、绝对路径不进入日志或 trace | +| 制品 | OCI 镜像、固定 digest、SBOM；首期不要求 Kubernetes | + +## 6. 端到端闭环总览 + +```mermaid +flowchart LR + G[治理预配置] --> L[飞书 OAuth 登录] + L --> B{绑定与状态有效?} + B -- 否 --> D[拒绝并审计] + B -- 是 --> T[MCP 会话] + T --> A[双层授权] + A --> R[读取 / 搜索 current] + A --> S[本地明确选择] + S --> V[构建 / 校验 / diff] + V --> C[人类一次性确认] + C --> Q[发布请求 + outbox] + Q --> W[worker Git/CAS] + W --> E[immutable release + current + index] + E --> K[MCP readback] + K --> Z[完成回执] + Z --> R + Q -. every step .-> U[三主体审计] + W -- 失败 --> F[failed / retry / recovery release] + F --> Q + X[撤权/停用] --> D +``` + +闭环定义：一次发布只有在 `release record completed ∩ Gitea commit 可读 ∩ immutable release 校验通过 ∩ current 指向该 release ∩ search index 同版本 ∩ MCP readback hash 一致 ∩ completed 审计已落盘` 时完成。任何一项失败都不得返回成功。 + +## 7. 每一步调用、功能与输出 + +下表是 Canvas 的文字真源。`A1` 为普通读，`A2` 为受控构建，`A3` 为 discussion 发布，`A4` 为 confirmed/恢复发布。 + +| 步骤 | 谁发起 | 调用内容 | 实现功能 | 成功输出 | 失败/审计 | +|---|---|---|---|---|---| +| S00 治理预配置 | 治理人员/运维 | 受控 migration/import；`user_identities`、`feishu_bindings`、`gitea_bindings`、`projects`、`project_grants` | 建立飞书稳定 ID、Gitea 数字 ID、项目和动作授权映射 | 版本化配置记录、导入报告、审计关联 ID | 冲突或重复即整批拒绝；不暴露普通 MCP 写工具 | +| S01 发现资源 | Agent Host | `POST /mcp`；`/.well-known/oauth-protected-resource` | 发现 MCP resource 与授权服务器 | PRM、授权服务器地址、resource/audience | Origin/Host/protocol 不合法即拒绝并记 `request_denied` | +| S02 飞书 OAuth | Agent adapter | Authorization Code＋PKCE → 授权服务器 → 飞书 authorize/token/user info | 验证真实飞书员工身份，抵抗 code/token 截获 | 飞书 claims、内部 subject 候选 | state/PKCE/tenant/redirect 不一致即失败；不落飞书明文 token | +| S03 绑定激活 | Identity federation adapter | 查询 `FeishuBinding`、`GiteaBinding`、`UserIdentity` | 仅激活唯一预配置的飞书—内部—Gitea 映射 | active internal `user_id` | 未配置进入 `binding_pending`；冲突/停用进入 denied；均审计 | +| S04 MCP 凭据 | Authorization Server | token/refresh/revoke；`AgentSession` | 为当前人和 Agent client 创建短期会话 | access token、session、scope、expiry | token 不进入业务日志；会话可即时撤销 | +| S05 身份自查 | 用户/Agent | `get_my_identity`、`get_my_project_roles` | 展示本人身份、绑定状态和可用角色，不接受参数冒充 | 脱敏 identity/role 摘要 | 只返回 token subject；记录 human/agent/service | +| S06 列出项目 | 用户/Agent | `list_authorized_projects` | 先查 ProjectGrant，再实时查 Gitea permission | 两层均允许的项目列表 | Gitea 不可用、任一层拒绝即 fail closed | +| S07 读取 current | 用户/Agent | `get_current_manifest`、`read_artifact`、`verify_release_hash` | 读取唯一 current 的 manifest、正文和校验信息 | project/release/content status/hash/content | 禁止 history/build/private source；每个 project 再鉴权 | +| S08 搜索 current | 用户/Agent | `search_current` → ProjectGrant/Gitea → `pg_trgm` | 仅在已授权项目 current 内进行中文搜索 | 带 project/release/hash 的命中片段 | 先过滤项目再查询；不做跨项目结果后过滤 | +| S09 本地选择 | 用户＋adapter | Local Source Gate；允许根、真实路径、类型、大小、secret/PII 预检 | 只读取用户明确选择的本地 Markdown/附件 | 文件数、相对 label、size/hash 预览 | 越界、符号链接、控制文件、秘密/PII 命中即本地阻断 | +| S10 人类确认来源 | 用户＋框架确认服务 | 展示选择清单 → 签发 selection confirmation | 确认上传范围，不把 Agent 的自然语言当授权 | 一次性确认、Selection Manifest | 用户取消或 manifest 变化即废弃；不上传未选内容 | +| S11 分块传输 | Agent adapter | `create_selection`、`append_selection_content` | 将选中内容以固定 chunk 送入隔离临时区 | selection ID、完整度、server-computed hash | 缺块、乱序、超时、hash 不符即废弃整个 selection | +| S12 构建预览 | 用户/Agent | `build_preview` → deterministic builder | 规范化 Markdown、收集附件、改写链接、生成 manifest | candidate artifact、candidate hash、构建报告 | 不由 LLM 决定确定性结果；同输入同版本 hash 相同 | +| S13 完整校验 | 用户/Agent | `validate_release_request` → schema/link/path/secret/PII/policy scanner | 拦截结构、路径、凭据、隐私和规则问题 | validation report、policy version、blocking findings | blocking finding 不得继续；例外必须引用受控记录 | +| S14 差异预览 | 用户/Agent | `preview_release_diff` → current reader | 把 candidate 与 `base_current` 比较 | 文件/章节/附件变化、candidate hash、base_current | current 已变化则标 stale，要求重新构建 | +| S15 发布确认 | 真实用户＋框架确认服务 | 固定展示 project/action/hash/base/diff → `confirmation_id` | 给 A3/A4 生成与精确请求 hash 绑定的一次性授权 | 5 分钟内有效的 confirmation ID | 不能复用、转让或跨 hash；Agent 原生 prompt 不是最终真源 | +| S16 提交发布 | Publisher/Agent | `submit_discussion_release` 或 `submit_confirmed_release` | 创建幂等发布记录并提交 outbox | release ID、queued 状态、correlation ID | 请求、release、outbox、审计同一事务；失败不入队 | +| S17 网关复核 | `contextd serve` | token/user/binding/session/grant/policy/Gitea/confirmation 全链检查 | 在写动作前再次执行双层权限和确认校验 | allowed decision＋policy evidence | 任一条件失败即 denied；不以工具参数覆盖主体 | +| S18 Worker 领取 | `contextd worker` | `FOR UPDATE SKIP LOCKED` claim outbox；idempotency key | 可靠领取一次发布任务，允许安全重试 | processing 状态、attempt、worker identity | 重复事件返回同一 release；审计 worker 主体 | +| S19 Git/CAS 发布 | worker | 临时 worktree、Gitea read/write credential、Git commit/push | 再验 `base_current`，生成完整新 `current/`，单 commit 非 force push | commit SHA、release manifest | non-fast-forward → `STALE_BASE`；token 不进命令行/日志 | +| S20 导出与切换 | worker | immutable export、checksum、原子 current pointer | 从 commit 生成不可变 release，并原子切换唯一 current | release path、current version、checksums | 校验失败不切 current；旧 release 保留供恢复 | +| S21 激活检索 | worker | 构建 `pg_trgm` search document/index | 让搜索版本与 current 保持一致 | `project_id＋release_id` index active | 索引失败则发布不 completed；不得搜索旧/半成品索引 | +| S22 MCP 读回 | worker/internal reader | `get_current_manifest`、`read_artifact` 等同业务读取链 | 用用户将使用的路径验证结果，不只检查磁盘 | readback release/hash/content status | Git/current/MCP 任一不一致即 failed，不能伪成功 | +| S23 完成回执 | serve/worker | 更新 `release_records`、写 completed audit、`get_release_status` | 对用户给出可验证发布结果 | release ID、commit、current/hash、readback、timestamps | completed 审计无法落盘则不返回 completed | +| S24 后续消费 | 用户/Agent | S07/S08 | 后续会话只消费唯一 current，闭合“发布→读取” | 与 S23 相同 release/hash | 若不一致触发完整性告警，停止扩散 | +| S25 审计查询 | 本人/审计人员 | `list_my_actions`、`trace_release`、`trace_correlation`、`verify_audit_event` | 查询脱敏行为、追踪发布全链并验证 hash chain | human/agent/service、decision、result、correlation | 查询也需授权并被审计；无审计写删工具 | +| S26 撤权/离职 | 治理人员/身份事件 | 受控更新 binding/grant/session；OAuth revoke | 使飞书、Gitea、内部权限或会话任一撤销立即生效 | revoked version、session invalidation、审计 | 下一次调用 fail closed；不等待 access token 自然到期 | +| S27 失败与重试 | 系统/Publisher | `get_release_status`、幂等重试、`cancel_precommit_release` | 区分可重试、需重建、需人工处置的失败 | stable error code、attempt、next action | 已产生 commit 后不可“删除历史式回滚” | +| S28 恢复发布 | Publisher＋确认人 | 从已知良好 release 新建 A4 release | 通过新 commit 恢复 current，保留完整历史 | 新 release/commit/current、恢复原因 | 仍需双层权限、完整检查和一次性确认 | + +## 8. 功能需求 + +### FR-01 身份与会话 + +- 每位用户必须独立 OAuth；同一 Agent Host 上不同用户的 token、session、审计主体不得串用。 +- 飞书身份键至少包含 `tenant_key＋open_id`，在权限允许时保留租户内稳定 `user_id`；邮箱、手机号、姓名不作为主键。 +- MCP resource server 不直接信任 Feishu token；由授权服务器完成联邦并签发 MCP 资源令牌。 +- 未预配置 GiteaBinding 的用户只能看到绑定待处理状态，不可列出项目。 +- access token、refresh/session、binding 和 grant 均可撤销；每次调用重新检查权限版本。 + +### FR-02 双层授权 + +- 第一层：内部 `ProjectGrant` 决定项目、角色、动作、有效期和 sensitivity policy。 +- 第二层：Gitea 当前仓库权限决定该 Gitea 账户是否仍可读取项目。 +- 有效权限是两层交集；禁止用并集、兜底角色或 Agent 声明放宽。 +- 首期不缓存 Gitea 的 allow 结果；Gitea 超时或错误时 fail closed。 +- A3/A4 另需一次性精确确认；确认不替代双层授权。 + +### FR-03 读取与搜索 + +- 只允许读取 `main/current` 对应的不可变 release。 +- 响应必须带 `project_id`、`release_id`、`content_status`、manifest/hash，便于 Agent 判断来源。 +- 搜索必须在 SQL 查询前确定授权项目集合，并以 project/release 作为强过滤条件。 +- 不返回构建临时区、私人来源、Git 历史、其他分支或未发布 candidate。 + +### FR-04 Local Source Gate + +- 允许根由企业/框架配置，正文和 Agent 无权更改。 +- 用户必须明确选择文件或章节；目录选择仅枚举该选择范围，禁止默认扫描整个工作区。 +- 解析真实路径后拒绝工作区外路径、符号链接逃逸、`.git`、凭据目录、隐藏控制文件和不允许的二进制。 +- 本地先做 secret/PII 预检，服务端收到后再次做完整策略检查；客户端通过不等于服务端放行。 +- 只传相对 source label，不传个人绝对路径；正文不进入普通日志、trace 或审计详情。 + +### FR-05 构建与验证 + +- builder 输入为 Selection Manifest＋内容＋固定 builder/policy/schema version。 +- 同输入和相同版本必须得到同 candidate hash。 +- validation 至少覆盖 schema、Markdown 结构、内部链接、附件引用、路径、凭据、PII、控制文件、大小和内容状态。 +- blocking finding 无法通过 Agent 解释绕过；例外必须是受控配置并进入审计。 + +### FR-06 发布 + +- `discussion` 与 `confirmed` 使用同一 pipeline；confirmed 需要更高权限/确认，但不复制另一套写入逻辑。 +- 提交必须引用 `candidate_hash＋base_current＋confirmation_id＋idempotency_key`。 +- 只有 project-scoped publish gateway credential 可以非 force push 受保护 `main`。 +- current 必须通过完整目录构建后原子切换，不能在服务目录逐文件修改。 + +### FR-07 审计 + +- 每次工具调用产生 `request_received → allowed/denied → completed/failed` 事件链。 +- 每个事件至少记录 human、agent、service、session、tool、action、project、request hash、policy、authorization、confirmation、result、correlation。 +- `request_received` 无法持久化时拒绝业务调用。 +- 普通运行身份无 `audit_events` update/delete；查询只走脱敏 view。 +- 事件使用 canonical JSON hash chain，每日生成签名 checkpoint 并纳入备份。 + +### FR-08 失败、撤权和恢复 + +- 对外返回稳定错误码和下一步建议，不泄露其他项目、主体或内部路径。 +- 可重试错误保持相同 idempotency key；current 已变化返回 `STALE_BASE` 并要求重建。 +- 已完成 Git commit 不做历史删除式回滚；恢复必须创建新 release。 +- 撤权后下一次调用即失败，并可通过 correlation 追溯撤销主体和影响会话。 + +## 9. MCP 工具清单 + +| 分组 | 工具 | 风险等级 | 是否需人类确认 | +|---|---|---:|---| +| 身份/读取 | `get_my_identity`、`list_authorized_projects`、`get_my_project_roles`、`get_current_manifest`、`read_artifact`、`search_current`、`verify_release_hash` | A1 | 否；客户端可保留普通 tool prompt | +| 选择/构建 | `create_selection`、`append_selection_content`、`build_preview`、`validate_release_request`、`preview_release_diff` | A2 | 来源上传前需要明确范围确认；不是发布确认 | +| 发布 | `submit_discussion_release` | A3 | 是，一次性精确确认 | +| 高等级发布/恢复 | `submit_confirmed_release` | A4 | 是，一次性精确确认＋更高角色 | +| 状态控制 | `get_release_status`、`cancel_precommit_release` | A1/A2 | 取消只允许 commit 前；记录审计 | +| 审计查询 | `list_my_actions`、`get_action_detail`、`trace_release`、`trace_correlation`、`list_project_audit_events`、`verify_audit_event` | A1/A2 | 按审计角色和项目范围授权 | + +以下能力绝不注册为普通 MCP tool：用户/Gitea 绑定写入、ProjectGrant 写入、数据库迁移、部署、备份/恢复、密钥管理、Gitea Admin、通用 Git、Shell/SQL、审计写入/删除、功能动作开关修改。 + +## 10. 数据与状态 + +### 10.1 核心数据对象 + +| 领域 | 对象 | +|---|---| +| 身份 | `UserIdentity`、`FeishuBinding`、`GiteaBinding`、`AgentSession`、`MCPToken/claims` | +| 授权 | `Project`、`ProjectGrant`、`PolicyVersion`、`Confirmation` | +| 来源与构建 | `Selection`、`SelectionChunk`、`Artifact`、`ValidationReport` | +| 发布 | `ReleaseRecord`、`CurrentVersion`、`IdempotencyRecord`、`OutboxEvent` | +| 搜索 | `CurrentSearchDocument(project_id, release_id, field, normalized_text)` | +| 审计 | `AuditEvent`、`AuditCheckpoint`、`Correlation` | + +### 10.2 状态机 + +```text +selection: created → receiving → sealed → consumed | expired | rejected +release: requested → queued → processing → committed → exported → indexed → readback_verified → completed + ↘ failed / stale_base / cancelled_before_commit +binding: pending → active → suspended | revoked +session: active → expired | revoked +``` + +- 不认识的状态一律拒绝，不自动映射为成功。 +- `completed` 是最终一致性事实，不等同于“任务已入队”或“Git push 已返回成功”。 +- `content_status`（discussion/confirmed）与 `release status`（queued/completed/failed）保持两个字段。 + +## 11. 安全默认值 + +以下值作为 C1 合成环境的可执行默认值；G0 可按安全评审收紧或调整，但不得取消对应控制。 + +| 参数 | 默认值 | +|---|---| +| MCP access token | 15 分钟；issuer/audience/resource/scope/client 必验 | +| AgentSession/refresh | 8 小时；撤权即时失效 | +| 发布 confirmation | 5 分钟、一次性、绑定 user/session/tool/project/request hash | +| Selection TTL | 30 分钟；完成立即清理，失败最长保留 30 分钟后清理 | +| Markdown 单文件 | 2 MiB | +| 允许附件 | `.png`、`.jpg`、`.jpeg`、`.webp`、`.pdf`；只作为受控附件，不自动执行 | +| 附件单文件 | 5 MiB | +| Bundle 总量 | 10 MiB、最多 100 个文件 | +| MCP chunk | 256 KiB 原始内容；每块带序号和 hash | +| 路径 | 仅中央配置允许根；拒绝 symlink/junction/reparse point 逃逸 | +| Gitea allow cache | 关闭；每次项目访问实时复核 | +| Idempotency | 同 key 24 小时内返回同一 release；payload hash 不同则冲突 | +| 普通日志 | 不记录 token、正文、附件、绝对路径、完整 diff | +| 审计试点保留建议 | 在线 365 天；checkpoint/备份 3 年，G0 结合制度确认 | +| 试点恢复建议 | RPO 24 小时、RTO 8 小时；G0 可收紧 | + +## 12. 非功能需求 + +### 12.1 性能与容量试点目标 + +- `get_my_identity`/项目列表：无外部故障时 p95 ≤ 2 秒。 +- current manifest/read：不含大正文传输时 p95 ≤ 2 秒。 +- 10 万个 current 文档以内的单项目中文搜索：p95 ≤ 3 秒；以合成和真实试点基准为准。 +- 10 MiB 以内发布从 queued 到 readback completed：p95 ≤ 60 秒，不以牺牲校验换取速度。 +- 单用户同时最多 3 个 receiving selection、1 个 processing release；每项目发布串行化。 + +### 12.2 可用性与一致性 + +- 试点目标月可用性 99.5%，不含已公告维护。 +- Gitea、数据库、授权服务器或审计写入不可用时，权限与发布 fail closed。 +- 读取可在 Git 暂时不可用时继续使用已校验的 current，但必须验证 manifest/hash；任何完整性异常立即停止读取。 +- 重启、worker 重复领取、网络超时不得产生两个 current 或重复 commit。 + +### 12.3 可观测性 + +- 公开指标：请求量、拒绝原因码、外部依赖延迟、outbox backlog、release 状态耗时、readback mismatch、撤权生效延迟。 +- trace 使用 correlation ID 串联 serve、DB、worker、Gitea、export、readback；不包含正文和秘密。 +- 审计是合规事实，普通日志和 trace 不能替代审计。 + +## 13. 异常与恢复矩阵 + +| 场景 | 系统行为 | 用户下一步 | +|---|---|---| +| 未预配置 Gitea 绑定 | `BINDING_PENDING`，不给项目列表 | 联系治理人员完成受控预配置 | +| ProjectGrant 允许但 Gitea 拒绝 | `PERMISSION_DENIED_SECOND_LAYER` | 检查 Gitea 项目成员关系；不得自动放宽 | +| Gitea 权限 API 超时 | `AUTHZ_DEPENDENCY_UNAVAILABLE`，fail closed | 稍后重试；审计保留依赖故障 | +| Local Source Gate 命中 secret/PII | 本地阻断且不传正文 | 移除/脱敏后重新选择 | +| 分块缺失/hash 不符 | selection rejected，全量清理 | 重新创建 selection | +| validation blocking finding | 不生成可发布确认 | 修正文档或走受控例外评审 | +| confirmation 过期/被用过 | `CONFIRMATION_INVALID` | 重新查看 diff 并确认 | +| `base_current` 已变化 | `STALE_BASE` | 重新 build/validate/diff/confirm | +| Git 已提交但 export/index/readback 失败 | release failed，保留 commit，不宣告 completed | 修复依赖后幂等续跑或发恢复 release | +| completed 审计落盘失败 | 不返回 completed | 系统重试，治理人员排查 audit store | +| 撤权/离职 | session/grant/binding version 失效 | 重新授权前任何访问均拒绝 | +| current 完整性异常 | 停止读取和扩散，触发告警 | 从已知良好 release 发起恢复发布 | + +## 14. 代码开发与实施拆解 + +### 14.1 C1 代码开发（需要 Verlit 另行授权） + +| 阶段 | 实现内容 | 明细产物 | 退出条件 | +|---|---|---|---| +| C1-00 | Codex/Claude Code adapter contract | MCP 配置样例、fake OAuth、确认和 Local Source Gate 契约测试 | 两个 adapter 使用同一工具 schema；单个失败不降低核心控制 | +| C1-01～03 | 工程、契约、领域、DB | Go module、contracts、migration、sqlc、测试夹具 | 离线 build/test，状态/约束/最小 DB role 通过 | +| C1-04～06 | OAuth、绑定、双层授权、MCP、审计 | authorization server 集成、Feishu/Gitea fake、middleware、outbox | 冒充、未绑定、撤权、审计中断用例均 fail closed | +| C1-07～08 | current 读取、中文搜索、Local Source Gate、build/validate | 第一/二批 MCP tools、`pg_trgm` benchmark、scanner | 跨项目、历史、越界路径、secret/PII、超限均阻断 | +| C1-09～10 | release/export/readback、审计查询、OTel | 第三/四批 tools、worker、Git fake、完整性验证 | 并发、幂等、失败续跑、三主体审计通过 | +| C1-11～12 | 安全/恢复测试与制品 | 测试报告、OCI、SBOM、checksum、运行手册 | M01～M10、开发态 T 用例通过；无秘密、无自动部署 | + +### 14.2 G0～G5 真实实施（需要单独授权且先确认第 17 节） + +1. G0：确认人、项目、OAuth/飞书/Gitea/服务器/审计/备份参数。 +2. G1：测试环境基础设施和合成用户/项目，不接真实内容。 +3. G2：导入真实绑定和 ProjectGrant，验证双层权限与撤权。 +4. G3：按“只读 → 构建 → discussion → confirmed/恢复”逐批开放工具。 +5. G4：安全、凭据轮换、备份和空环境恢复。 +6. G5：一个低敏感真实项目试点，以真实用户结果和止损矩阵决定是否扩展。 + +## 15. 验收标准 + +### 15.1 产品级必须通过 + +- 两名用户通过各自 OAuth 连接同一 MCP，身份、项目、token、session、审计不串用。 +- 未绑定、内部授权拒绝、Gitea 拒绝、Gitea 不可用、撤权五类场景全部 fail closed。 +- Agent 无法通过工具参数、prompt、伪造 username 或复用 confirmation 提升权限。 +- Local Source Gate 只能上传明确选择内容；越界、符号链接、secret/PII、超限和 hash 错误全部阻断。 +- discussion/confirmed 均经过 build、validation、diff、确认、CAS、Git、export、index、readback。 +- 并发发布不会产生两个 current；失败不会返回伪成功。 +- 发布回执、Gitea commit、immutable release、current、search、MCP readback 的 release/hash 完全一致。 +- human、agent、service 三主体链完整；审计事件可验证且普通角色无法修改删除。 +- 撤权后下一次调用拒绝；备份可在隔离环境恢复并使旧凭据失效。 + +### 15.2 止损信号 + +- 出现共享账号、共享 token、绕过 MCP 的业务写入口。 +- 出现内部授权或 Gitea 任一层被忽略。 +- Agent 能读取未选择本地内容、未授权项目、历史或构建区。 +- 出现两个 current、force push、Git 历史删除或无法恢复的备份。 +- 审计可被普通运行身份修改/删除，或关键动作在无 `request_received` 情况下执行。 +- 为兼容单个 Agent 而取消 OAuth、确认、Local Source Gate 或审计。 + +命中任一项即停止新增项目和扩大用户范围，先恢复到只读或 `forced_off`。 + +## 16. PRD 追溯矩阵 + +| 本 PRD 内容 | 上游依据 | 关系 | +|---|---|---| +| 一项目一私仓、唯一 current、发布状态与内容状态 | 原 v1 | 原样继承 | +| MCP 唯一入口、飞书身份、双层权限、三主体审计 | v1.1 覆盖方案 | 差量补充 | +| Agent adapter、Go/PostgreSQL/Gitea/outbox | 技术栈设计 | 实现选择 | +| 成熟授权服务器 | MCP OAuth 安全边界 | 补齐实现责任，不改业务目标 | +| 飞书—Gitea 预配置绑定 | 双层权限的安全开户流程 | 补齐未绑定/冒充路径 | +| `pg_trgm` 中文检索 | “只搜索授权 current”的实现 | 修正中文检索技术选型 | +| Skill Registry 后置 | 当前版本边界 | 明确不纳入 v1.1 | + +## 17. 仍需确认的实施参数 + +这些不是架构问题，也不需要重新生成设计稿；它们按“开始哪一步、确认哪一项”处理。 + +| Gate | 最迟时间 | 必须提供/决定 | 没有时的处理 | +|---|---|---|---| +| DG-01 主栈 | C1-01 前 | 团队是否能长期维护 Go | 否则暂停并重新评审 TypeScript 主栈，不双栈混用 | +| DG-02 OAuth AS | C1-04 前 | 可复用的成熟 OAuth/OIDC Authorization Server；若无，批准独立产品及责任人 | 不实现真实 token 签发，只保留 fake auth | +| DG-03 Agent 版本 | C1-00 前 | Codex、Claude Code 支持版本与企业配置分发方式 | 只做通用 contract，不声明该 adapter 可用 | +| DG-04 确认服务 | C1-05 前 | 签名算法、密钥托管、TTL、单次消费存储 | A3/A4 工具不注册 | +| DG-05 Local Source Policy | C1-08 前 | 允许根、类型、大小、secret/PII 规则、临时保留 | 使用第 11 节合成测试默认值，不接真实文件 | +| DG-06 飞书 | G0 前 | 自建 App、管理员、redirect domain、tenant、scope | 不连接飞书 | +| DG-07 Gitea | G0 前 | 新建/复用、版本、管理员、权限 API、项目级服务凭据 | 不连接 Gitea | +| DG-08 人和项目 | G2 前 | 试点项目、成员、Publisher、绑定清单、ProjectGrant、治理/审计责任人 | 不导入真实主体和内容 | +| DG-09 环境 | G1 前 | Linux/容器、域名/TLS、PostgreSQL、反向代理、密钥与监控产品 | 不部署 | +| DG-10 治理 | G1/G4 前 | 审计保留、脱敏、RPO/RTO、备份路径、事故联系人 | 不进入真实试点 | + +## 18. 评审与下一步 + +### 18.1 当前可以确认的结论 + +- PRD、技术方案和闭环流程可以定稿为“review-ready”。 +- 当前没有必要重新改写原 v1，也不需要创建新的业务版本。 +- 不需要安装新的绘图或文档能力；本 vault 可直接承载 Markdown PRD 与 Obsidian Canvas。 +- 当前不部署、不运行、不连接飞书/Gitea/服务器、不创建代码仓库。 + +### 18.2 下一条授权应如何表述 + +若要进入代码阶段，可明确下达： + +> 进入 Gitea 知识库 v1.1 的 C1 代码开发，只使用 fake Feishu/Gitea、合成身份和本地临时 PostgreSQL；先执行 C1-00～C1-03，不连接真实环境、不部署。 + +若要进入真实实施，必须在 C1 制品通过验收后，再按第 17 节补齐对应参数并单独授权 G0/G1，不能从“文档完成”直接跳到生产部署。 diff --git a/Gitea知识库/Gitea知识库 v1.1 完整流程闭环.canvas b/Gitea知识库/Gitea知识库 v1.1 完整流程闭环.canvas new file mode 100644 index 0000000..45abb4c --- /dev/null +++ b/Gitea知识库/Gitea知识库 v1.1 完整流程闭环.canvas @@ -0,0 +1,94 @@ +{ + "nodes":[ + {"id":"g-control","type":"group","x":6940,"y":0,"width":2240,"height":3880,"color":"1","label":"E. 审计、拒绝、撤权、失败与恢复"}, + {"id":"g-release","type":"group","x":0,"y":2060,"width":6500,"height":820,"color":"6","label":"D. 发布事务、Git、current、检索与读回"}, + {"id":"g-auth","type":"group","x":0,"y":0,"width":5060,"height":780,"color":"5","label":"A. 治理、登录、绑定与双层授权"}, + {"id":"g-build","type":"group","x":0,"y":1040,"width":5060,"height":760,"color":"3","label":"C. 明确选择、构建、校验与确认"}, + {"id":"g-read","type":"group","x":5280,"y":0,"width":1360,"height":780,"color":"4","label":"B. 唯一 current 读取闭环"}, + {"id":"s12","type":"text","text":"S12 构建预览\n\n调用：build_preview → deterministic builder/goldmark\n\n功能：规范化 Markdown、附件与链接，生成 manifest\n\n输出：candidate artifact/hash、构建报告\n\n审计：记录 builder/schema version；LLM 不决定构建结果","x":2260,"y":1180,"width":440,"height":500,"color":"3"}, + {"id":"s09","type":"text","text":"S09 本地明确选择\n\n调用：Local Source Gate → 允许根/realpath/类型/大小/secret/PII\n\n功能：只读取用户点选的 Markdown/附件\n\n输出：相对 label、size、hash 预览\n\n审计：不记录绝对路径/正文；越界、symlink、控制文件本地阻断","x":100,"y":1180,"width":440,"height":500,"color":"3"}, + {"id":"s16","type":"text","text":"S16 提交发布\n\n调用：submit_discussion_release / submit_confirmed_release\n\n功能：创建幂等 release record＋outbox\n\n输出：release ID、queued、correlation ID\n\n审计：request/release/outbox/audit 同一事务","x":100,"y":2200,"width":440,"height":520,"color":"6"}, + {"id":"s24","type":"text","text":"S24 后续消费闭环\n\n调用：再次执行 S07/S08\n\n功能：新会话和其他 Agent 只消费新 current\n\n输出：与 S23 相同 release/hash\n\n审计：不一致触发完整性告警并停止扩散","x":5860,"y":2200,"width":440,"height":520,"color":"6"}, + {"id":"s13","type":"text","text":"S13 完整校验\n\n调用：validate_release_request → schema/link/path/secret/PII/policy\n\n功能：拦截结构、安全和治理问题\n\n输出：validation report、policy version\n\n审计：blocking finding 不可被 prompt 绕过","x":2980,"y":1180,"width":440,"height":500,"color":"3"}, + {"id":"s14","type":"text","text":"S14 差异预览\n\n调用：preview_release_diff → current reader\n\n功能：比较 candidate 与 base_current\n\n输出：文件/章节/附件变化、candidate hash\n\n审计：current 变化即 stale，要求重新构建","x":3700,"y":1180,"width":440,"height":500,"color":"3"}, + {"id":"s19","type":"text","text":"S19 Git/CAS 发布\n\n调用：临时 worktree＋Gitea project credential＋git commit/push\n\n功能：复核 base_current，完整生成 current，单 commit 非 force push\n\n输出：commit SHA、release manifest\n\n审计：non-fast-forward→STALE_BASE；token 不入命令行/日志","x":2260,"y":2200,"width":440,"height":520,"color":"6"}, + {"id":"s10","type":"text","text":"S10 确认来源范围\n\n调用：框架展示清单 → selection confirmation\n\n功能：确认将要传输的精确内容范围\n\n输出：不可变 Selection Manifest\n\n审计：取消或 manifest 变化即废弃；Agent 自述不算授权","x":820,"y":1180,"width":440,"height":500,"color":"3"}, + {"id":"s20","type":"text","text":"S20 不可变导出/current\n\n调用：export、checksum、atomic pointer switch\n\n功能：从 commit 生成 immutable release 并切唯一 current\n\n输出：release path、current version、checksums\n\n审计：校验失败不切 current；旧 release 保留","x":2980,"y":2200,"width":440,"height":520,"color":"6"}, + {"id":"s21","type":"text","text":"S21 激活中文检索\n\n调用：规范化 search document＋pg_trgm GIN/GiST index\n\n功能：让搜索版本与 current 一致\n\n输出：project＋release index active\n\n审计：索引失败则 release 不 completed","x":3700,"y":2200,"width":440,"height":520,"color":"6"}, + {"id":"s08","type":"text","text":"S08 中文搜索 current\n\n调用：search_current → AuthZ → PostgreSQL pg_trgm\n\n功能：按 project＋release 做中文子串/相似度检索\n\n输出：带 release/hash 的命中\n\n审计：先授权过滤再查询，不做模型端跨项目过滤","x":6100,"y":140,"width":440,"height":500,"color":"4"}, + {"id":"s11","type":"text","text":"S11 分块传输\n\n调用：create_selection / append_selection_content\n\n功能：送入隔离临时区并复算完整 hash\n\n输出：selection ID、完整度、server hash\n\n审计：缺块、乱序、超时、hash 不符时整包拒绝","x":1540,"y":1180,"width":440,"height":500,"color":"3"}, + {"id":"s17","type":"text","text":"S17 网关最终复核\n\n调用：token ∩ user ∩ binding ∩ session ∩ grant ∩ policy ∩ Gitea ∩ confirmation\n\n功能：写前再次执行双层权限与精确确认\n\n输出：allowed decision/evidence\n\n审计：任一失败即 denied；主体不取自工具参数","x":820,"y":2200,"width":440,"height":520,"color":"6"}, + {"id":"s18","type":"text","text":"S18 Worker 领取\n\n调用：FOR UPDATE SKIP LOCKED claim outbox＋idempotency key\n\n功能：可靠领取并支持重复安全执行\n\n输出：processing、attempt、worker identity\n\n审计：重复请求归并同一 release","x":1540,"y":2200,"width":440,"height":520,"color":"6"}, + {"id":"audit","type":"text","text":"强制审计总线（覆盖 S00～S28）\n\n调用：Audit Middleware＋业务事务＋Outbox Worker\n\n事件：request_received → allowed/denied → completed/failed\n\n主体：human＋agent＋service＋session＋tool＋project＋policy＋confirmation＋result＋correlation\n\n实现：append-only、canonical JSON hash chain、每日签名 checkpoint\n\n规则：request_received 无法落盘即拒绝；审计写入/删除不是 MCP tool","x":7060,"y":140,"width":860,"height":460,"color":"1"}, + {"id":"deny","type":"text","text":"Fail Closed 拒绝出口\n\n来源：未绑定、停用、token/session 无效、ProjectGrant 拒绝、Gitea 拒绝/故障、确认无效、策略阻断、完整性异常\n\n输出：稳定错误码＋脱敏 next_action＋correlation ID\n\n功能：任何依赖不确定都不降级为 allow\n\n审计：记录决策依据，不泄露他人或其他项目","x":8200,"y":140,"width":860,"height":460,"color":"1"}, + {"id":"s25","type":"text","text":"S25 审计查询\n\n调用：list_my_actions / trace_release / trace_correlation / verify_audit_event\n\n功能：本人或审计角色查看脱敏行为并验证事件链\n\n输出：三主体、decision、result、correlation\n\n审计：查询本身也被审计；无 update/delete","x":7060,"y":780,"width":860,"height":420,"color":"1"}, + {"id":"s26","type":"text","text":"S26 撤权/离职\n\n调用：受控 binding/grant/session version update＋OAuth revoke\n\n功能：任一层撤销后立即失效\n\n输出：revoked version、session invalidation\n\n审计：下一次调用进入 Fail Closed，不等待 token 到期","x":8200,"y":780,"width":860,"height":420,"color":"1"}, + {"id":"s27","type":"text","text":"S27 失败与幂等重试\n\n调用：get_release_status / same idempotency key / cancel_precommit_release\n\n功能：区分 transient、STALE_BASE、blocking、post-commit failure\n\n输出：stable error、attempt、next action\n\n审计：commit 前可取消；commit 后不删除历史","x":7060,"y":1380,"width":860,"height":440,"color":"1"}, + {"id":"s07","type":"text","text":"S07 读取唯一 current\n\n调用：get_current_manifest / read_artifact / verify_release_hash\n\n功能：只读授权项目 current\n\n输出：project、release、content_status、hash、正文\n\n审计：禁止 history/build/private source","x":5380,"y":140,"width":440,"height":500,"color":"4"}, + {"id":"s15","type":"text","text":"S15 发布确认\n\n调用：框架确认服务签发 confirmation_id\n\n功能：将真实用户确认绑定到 tool/project/hash/base/diff\n\n输出：5 分钟一次性凭证\n\n审计：不可转让、复用或跨 hash；原生 tool prompt 只作交互保护","x":4420,"y":1180,"width":440,"height":500,"color":"3"}, + {"id":"decision","type":"text","text":"实施前硬门（不是方案缺陷）\n\nC1-01：确认团队维护 Go\nC1-04：选择成熟 OAuth/OIDC Authorization Server\nC1-00：固定 Codex/Claude Code 支持版本\nC1-05：确认 confirmation 签名/密钥/TTL\nC1-08：确认 Local Source Gate 策略\nG0/G1：飞书 App、Gitea、服务器、TLS、PostgreSQL、监控/密钥\nG2：试点项目、绑定清单、ProjectGrant、Publisher/治理/审计责任人\nG4：审计保留、脱敏、RPO/RTO、备份与事故联系人\n\n没有对应参数时停在该 Gate，不部署、不连接、不自动降级。","x":7060,"y":2020,"width":2000,"height":560,"color":"2"}, + {"id":"prd","type":"file","file":"3-业务线/Gitea知识库/Gitea知识库 v1.1 产品需求文档 PRD.md","x":7060,"y":2780,"width":860,"height":460,"color":"5"}, + {"id":"baseline","type":"file","file":"3-业务线/Gitea知识库/公司共享 Context 项目仓库发布方案 v1.md","x":8200,"y":2780,"width":860,"height":460,"color":"6"}, + {"id":"meta","type":"text","text":"Canvas 元数据\n\n责任人：Verlit　最后更新时间：2026-08-10　最后更新人：Codex\n文件 SHA-256 登记位置：Gitea知识库/resources.md\n范围：本地 C0 工程设计产物；未部署、未运行、未连接远端","x":7060,"y":3440,"width":2000,"height":280,"color":"5"}, + {"id":"s22","type":"text","text":"S22 MCP 读回\n\n调用：与用户相同的 current manifest/read_artifact 链\n\n功能：从真实消费入口验证 release/hash/status\n\n输出：readback evidence\n\n审计：Git/current/MCP 任一不一致即 failed","x":4420,"y":2200,"width":440,"height":520,"color":"6"}, + {"id":"s23","type":"text","text":"S23 完成回执\n\n调用：release_records completed＋completed audit＋get_release_status\n\n功能：给出可验证的最终发布事实\n\n输出：release、commit、current/hash、readback、timestamps\n\n审计：completed 事件不能落盘就不返回成功","x":5140,"y":2200,"width":440,"height":520,"color":"6"}, + {"id":"s28","type":"text","text":"S28 恢复发布\n\n调用：从已知良好 release 创建新的 A4 candidate → S15 确认 → 正常发布链\n\n功能：用新 commit 恢复 current，保留完整历史\n\n输出：新 release/commit/current、恢复原因\n\n审计：仍需双层权限、validation 和一次性确认","x":8200,"y":1380,"width":860,"height":440,"color":"1"}, + {"id":"s01","type":"text","text":"S01 发现 MCP 资源\n\n调用：POST /mcp → 401；/.well-known/oauth-protected-resource\n\n功能：让 Agent Host 获取 resource/audience 和授权服务器\n\n输出：PRM、OAuth metadata\n\n审计：Origin/Host/protocol 非法即 request_denied","x":820,"y":140,"width":440,"height":500,"color":"5"}, + {"id":"s02","type":"text","text":"S02 飞书 OAuth\n\n调用：Authorization Code＋PKCE → OAuth AS → 飞书 authorize/token/user_info\n\n功能：确认真实员工身份\n\n输出：飞书 claims、内部 subject 候选\n\n审计：state/PKCE/tenant/redirect；不保存飞书明文 token","x":1540,"y":140,"width":440,"height":500,"color":"5"}, + {"id":"s05","type":"text","text":"S05 身份自查\n\n调用：get_my_identity / get_my_project_roles\n\n功能：展示 token subject 的绑定和角色摘要\n\n输出：脱敏 identity/role\n\n审计：human＋agent＋service；不接受 user_id 参数冒充","x":3700,"y":140,"width":440,"height":500,"color":"5"}, + {"id":"s03","type":"text","text":"S03 绑定激活\n\n调用：查询 UserIdentity、FeishuBinding、预配置 GiteaBinding\n\n功能：激活唯一飞书—内部—Gitea 映射\n\n输出：active internal user_id\n\n审计：未配置→binding_pending；冲突/停用→denied","x":2260,"y":140,"width":440,"height":500,"color":"5"}, + {"id":"s04","type":"text","text":"S04 MCP 凭据与会话\n\n调用：OAuth AS token/refresh/revoke；创建 AgentSession\n\n功能：逐用户、逐 client 的短期会话\n\n输出：access token、scope、expiry、session\n\n审计：令牌不入业务日志；撤销即时生效","x":2980,"y":140,"width":440,"height":500,"color":"5"}, + {"id":"s00","type":"text","text":"S00 治理预配置\n\n调用：受控 migration/import → UserIdentity / FeishuBinding / GiteaBinding / ProjectGrant\n\n功能：建立真实主体、Gitea 数字 ID 和项目动作映射\n\n输出：版本化配置、导入报告、correlation ID\n\n审计：治理主体＋变更前后 hash；不开放普通 MCP 写工具","x":100,"y":140,"width":440,"height":500,"color":"5"}, + {"id":"s06","type":"text","text":"S06 列出授权项目\n\n调用：list_authorized_projects → ProjectGrant → Gitea live permission\n\n功能：计算两层权限交集\n\n输出：两层都允许的项目\n\n审计：Gitea 故障或任一层拒绝均 fail closed","x":4420,"y":140,"width":440,"height":500,"color":"5"} + ], + "edges":[ + {"id":"e0001","fromNode":"s00","fromSide":"right","toNode":"s01","toSide":"left","label":"预配置完成"}, + {"id":"e0102","fromNode":"s01","fromSide":"right","toNode":"s02","toSide":"left","label":"进入 OAuth"}, + {"id":"e0203","fromNode":"s02","fromSide":"right","toNode":"s03","toSide":"left","label":"飞书 claims"}, + {"id":"e0304","fromNode":"s03","fromSide":"right","toNode":"s04","toSide":"left","label":"绑定 active"}, + {"id":"e0405","fromNode":"s04","fromSide":"right","toNode":"s05","toSide":"left","label":"逐用户 token"}, + {"id":"e0506","fromNode":"s05","fromSide":"right","toNode":"s06","toSide":"left","label":"确认本人主体"}, + {"id":"e0607","fromNode":"s06","fromSide":"right","toNode":"s07","toSide":"left","label":"只读分支"}, + {"id":"e0708","fromNode":"s07","fromSide":"right","toNode":"s08","toSide":"left","label":"读取或搜索"}, + {"id":"e0807","fromNode":"s08","fromSide":"bottom","toNode":"s07","toSide":"bottom","label":"继续消费 current"}, + {"id":"e0609","fromNode":"s06","fromSide":"bottom","toNode":"s09","toSide":"top","label":"构建/发布分支"}, + {"id":"e0910","fromNode":"s09","fromSide":"right","toNode":"s10","toSide":"left","label":"选择预览"}, + {"id":"e1011","fromNode":"s10","fromSide":"right","toNode":"s11","toSide":"left","label":"manifest confirmed"}, + {"id":"e1112","fromNode":"s11","fromSide":"right","toNode":"s12","toSide":"left","label":"selection sealed"}, + {"id":"e1213","fromNode":"s12","fromSide":"right","toNode":"s13","toSide":"left","label":"candidate hash"}, + {"id":"e1314","fromNode":"s13","fromSide":"right","toNode":"s14","toSide":"left","label":"validation pass"}, + {"id":"e1415","fromNode":"s14","fromSide":"right","toNode":"s15","toSide":"left","label":"精确 diff"}, + {"id":"e1516","fromNode":"s15","fromSide":"bottom","toNode":"s16","toSide":"top","label":"一次性确认"}, + {"id":"e1617","fromNode":"s16","fromSide":"right","toNode":"s17","toSide":"left","label":"release request"}, + {"id":"e1718","fromNode":"s17","fromSide":"right","toNode":"s18","toSide":"left","label":"allowed＋outbox"}, + {"id":"e1819","fromNode":"s18","fromSide":"right","toNode":"s19","toSide":"left","label":"worker claim"}, + {"id":"e1920","fromNode":"s19","fromSide":"right","toNode":"s20","toSide":"left","label":"commit SHA"}, + {"id":"e2021","fromNode":"s20","fromSide":"right","toNode":"s21","toSide":"left","label":"current switched"}, + {"id":"e2122","fromNode":"s21","fromSide":"right","toNode":"s22","toSide":"left","label":"index active"}, + {"id":"e2223","fromNode":"s22","fromSide":"right","toNode":"s23","toSide":"left","label":"readback match"}, + {"id":"e2324","fromNode":"s23","fromSide":"right","toNode":"s24","toSide":"left","label":"completed receipt"}, + {"id":"e2407","fromNode":"s24","fromSide":"top","toNode":"s07","toSide":"bottom","label":"发布→消费闭环"}, + {"id":"ea04","fromNode":"s04","fromSide":"top","toNode":"audit","toSide":"left","label":"身份/会话事件"}, + {"id":"ea08","fromNode":"s08","fromSide":"right","toNode":"audit","toSide":"left","label":"读取事件"}, + {"id":"ea15","fromNode":"s15","fromSide":"right","toNode":"audit","toSide":"left","label":"确认事件"}, + {"id":"ea23","fromNode":"s23","fromSide":"right","toNode":"audit","toSide":"bottom","label":"发布完成事件"}, + {"id":"ea25","fromNode":"audit","fromSide":"bottom","toNode":"s25","toSide":"top","label":"脱敏查询/验证"}, + {"id":"ea26","fromNode":"s26","fromSide":"top","toNode":"audit","toSide":"right","label":"撤权事件"}, + {"id":"ed03","fromNode":"s03","fromSide":"top","toNode":"deny","toSide":"left","label":"未绑定/冲突"}, + {"id":"ed06","fromNode":"s06","fromSide":"top","toNode":"deny","toSide":"left","label":"双层权限失败"}, + {"id":"ed09","fromNode":"s09","fromSide":"right","toNode":"deny","toSide":"bottom","label":"来源策略阻断"}, + {"id":"ed13","fromNode":"s13","fromSide":"right","toNode":"deny","toSide":"bottom","label":"validation 阻断"}, + {"id":"ed17","fromNode":"s17","fromSide":"right","toNode":"deny","toSide":"bottom","label":"写前拒绝"}, + {"id":"ed22","fromNode":"s22","fromSide":"right","toNode":"deny","toSide":"bottom","label":"完整性失败"}, + {"id":"e262d","fromNode":"s26","fromSide":"top","toNode":"deny","toSide":"bottom","label":"即时失效"}, + {"id":"ef1927","fromNode":"s19","fromSide":"right","toNode":"s27","toSide":"left","label":"stale/transient"}, + {"id":"ef2227","fromNode":"s22","fromSide":"right","toNode":"s27","toSide":"left","label":"post-commit failure"}, + {"id":"e2728","fromNode":"s27","fromSide":"right","toNode":"s28","toSide":"left","label":"需要恢复时"}, + {"id":"e2815","fromNode":"s28","fromSide":"left","toNode":"s15","toSide":"right","label":"新 A4 candidate 重新确认"}, + {"id":"e2712","fromNode":"s27","fromSide":"left","toNode":"s12","toSide":"right","label":"STALE_BASE 重新构建"}, + {"id":"e2718","fromNode":"s27","fromSide":"left","toNode":"s18","toSide":"right","label":"瞬时故障幂等续跑"}, + {"id":"edprd","fromNode":"decision","fromSide":"bottom","toNode":"prd","toSide":"top","label":"完整需求与 Gate"}, + {"id":"ebase","fromNode":"decision","fromSide":"bottom","toNode":"baseline","toSide":"top","label":"v1 冻结基线"}, + {"id":"eprdbase","fromNode":"prd","fromSide":"right","toNode":"baseline","toSide":"left","label":"继承＋v1.1 差量，不改原文"} + ] +} \ No newline at end of file diff --git a/Gitea知识库/_context.md b/Gitea知识库/_context.md new file mode 100644 index 0000000..9d05a3e --- /dev/null +++ b/Gitea知识库/_context.md @@ -0,0 +1,134 @@ +--- +type: 业务线 +name: Gitea知识库 +status: 活跃 +role: 主导 +stage: G0 基础环境实施进行中，Gitea、MySQL 与首个管理员已就绪，域名、备份与试点尚未配置 +owner: Verlit +last_progress_at: 2026-08-11 +last_updated_at: 2026-08-11 +last_updated_by: Codex +hash: sha256:cd2f0fdc51f900558204909b73971faececb23814206db11a58d1313352e5242 +hash_scope: Markdown 正文（从一级标题开始至文件末尾）的 UTF-8 SHA-256 +depends_knowledge: [] +shared_resources: [] +--- + +# Gitea知识库 + +## 业务目的 + +建设一条受控的公司共享 Context 发布链：个人继续使用自己的创作工具，只将明确选择的材料构建为项目发布物，经质量、安全、权限和并发检查后写入按项目隔离的 Gitea 私有仓库，再以唯一的只读 `main/current` 提供给项目成员和 Agent。 + +Gitea 是公司 Git 远端、项目权限和版本历史层，不是这条业务线的全部目标。业务目标是让公司共享 Context 具备明确发布、状态区分、统一读取、审计、撤权、回读、备份和恢复能力。 + +## 长期战略定位 + +本业务线建设企业内部 AI 的共享 Context 与权限治理底座，长期主线仍是“先建立可靠知识库，再扩展更完整的 Agent 能力”。v1.1 的日常入口已经是 Agent＋MCP，但 Agent 只调用受控工具；知识库的确定性构建、权限、发布事务、current 和审计仍由服务端能力承载。 + +本业务线不默认承接所有企业 AI 产品形态。v1.1 已包含飞书身份映射、内部动态授权、Gitea 二次复核、受控发布和逐调用审计；Skill Registry、飞书内容来源和更高阶 Agent 协同仍需独立后续版本。 + +## 当前阶段 + +`公司共享 Context 项目仓库发布方案 v1` 已从收集箱归位到本业务线，并恢复为当前设计基线。原方案已经冻结的项目仓库、权限、发布、`current`、内容状态和 Agent 读取模型不再作为待选方案重新设计。 + +`C0 工程设计构建` 的 v1.1 口径更新已经完成。2026-08-11，Verlit 明确授权进入范围受限的 G0 基础实施：目标主机为 `120.27.248.208`，服务器范围为 `/`，但写入只允许落在 Gitea 自身的二进制、账号、配置、数据目录和 systemd 服务；共享主机上的其他业务代码与服务不得变动。 + +Gitea 1.26.4 基础服务已安装并仅监听 `127.0.0.1:3000`，MySQL 专用数据库配置、自动迁移、安全密钥、安装锁、配置权限收紧和首个管理员均已完成，本机主页与 `/api/healthz` 验证通过。正式域名/HTTPS、反向代理、备份、组织、仓库、细分权限和业务知识发布仍未配置；平台代码开发仍未授权，不能因为基础服务已启动而视为完整 G0/G1 验收或生产投用。 + +## 业务边界 + +### 包含 + +- 个人工作区到公司项目仓库的单向明确发布； +- 一项目一私有仓库的权限边界，以及成员、发布者、维护者、Agent 和服务身份； +- 飞书登录绑定内部稳定用户和 Gitea 账户、内部 ProjectGrant＋Gitea 权限双层限制； +- MCP 唯一用户业务入口、质量安全检查、发布网关、受保护 `main`、`current` 原子导出和发布回执； +- `current / superseded / retired` 技术状态与 `discussion / confirmed` 内容状态； +- 人和 Agent 的项目级读取、受控 A3/A4 发布请求、发布后读回、冲突阻断和恢复发布； +- 每次 MCP 调用的 human＋agent＋service 强制审计； +- Gitea、MCP、身份权限库、审计、异机备份、恢复演练和真实试点。 + +### 不包含 + +- 全量同步个人 Vault、个人 Git 历史或私人过程材料； +- 私人来源与企业 `current` 的双向同步或自动发布； +- 在同一仓库内用文件夹模拟项目权限隔离； +- 通用审批平台、PR/MR、多级会签、飞书内容来源、Skill Registry、自定义业务 Web 或跨项目治理； +- 将审计写入/删除、Gitea Admin、SSH、SQL、部署、备份、密钥和权限写入暴露为普通 MCP 工具； +- 未经确认的仓库创建、成员邀请、权限调整和业务知识发布； +- 把设计基线解释为系统已经部署或试点已经验收。 + +## 责任人与主要产物 + +- 责任人：Verlit +- 当前主要产物：冻结 v1 基线、v1.1 MCP-first 差量设计、完整 PRD、Obsidian Canvas 流程闭环图、设计追溯、工程构建规格、开发任务分解、未来实施方案、实施准入参数、验收与止损矩阵、业务线治理记录 +- 后续主要产物：MCP Gateway、身份绑定与权限库、强制审计、试点登记、权限矩阵、项目仓库、发布网关、`current` 读取端口、发布回执、备份恢复和试点验收记录 + +## 资源来源 + +- `3-业务线/Gitea知识库/公司共享 Context 项目仓库发布方案 v1.md` +- `0-收集箱/临时待归属/2026-08-03-公司共享Context发布与AI协同框架/` +- 上述方案包中的最终一致性检查与相关设计文档 + +v1 主方案是发布与仓库基线，v1.1 差量设计只覆盖 MCP、身份、权限、Agent 和审计的明确事项；两者按版本顺序共同构成当前目标。方案包补充接口契约、安全、权限、运维和执行细节，历史审查材料不覆盖版本真源。 + +## 可调用能力与限制 + +### 当前允许 + +- 只读检查本地方案、目录和元数据； +- 在本业务线内整理 v1/v1.1 设计基线、版本关系、工程规格、开发任务、决策和未来实施参数； +- 对主方案与补充方案做一致性校验； +- 准备不含秘密的配置、接口、测试、风险和验收规格； +- 在 Verlit 本轮明确授权内维护目标主机上的 Gitea 基础服务，并保持只监听 `127.0.0.1:3000`。 + +### 当前禁止 + +- 未经新的明确授权升级、重装、卸载或公开暴露 Gitea； +- 创建平台代码仓库、编写或运行系统代码； +- 修改宝塔/Nginx、防火墙、现有业务代码、Redis、PHP 或其他非 Gitea 服务； +- 猜测、复用或修改共享主机上其他业务的数据库； +- 创建远端组织、仓库、用户、Token、Webhook 或 CI； +- 向任何远端仓库推送、同步或发布； +- 在未确认试点范围与责任人前向试点仓库发布业务知识资产。 + +## 沉淀位置 + +- 业务上下文：当前文件 +- v1 设计基线：`3-业务线/Gitea知识库/公司共享 Context 项目仓库发布方案 v1.md` +- v1.1 差量覆盖层：`3-业务线/Gitea知识库/公司共享 Context MCP-first 身份与审计方案 v1.1.md` +- v1.1 技术栈与详细实施设计：`3-业务线/Gitea知识库/v1.1-技术栈与详细实施设计.md` +- v1.1 产品需求文档：`3-业务线/Gitea知识库/Gitea知识库 v1.1 产品需求文档 PRD.md` +- v1.1 完整流程闭环图：`3-业务线/Gitea知识库/Gitea知识库 v1.1 完整流程闭环.canvas` +- 设计追溯：`3-业务线/Gitea知识库/v1-设计追溯与版本关系.md` +- 工程构建规格：`3-业务线/Gitea知识库/v1-工程构建规格.md` +- 开发任务分解：`3-业务线/Gitea知识库/v1-开发任务分解.md` +- 实施参数：`3-业务线/Gitea知识库/v1-实施参数与决策清单.md` +- 详细实施方案：`3-业务线/Gitea知识库/v1-详细实施方案.md` +- 验收与止损：`3-业务线/Gitea知识库/v1-验收与止损矩阵.md` +- 任务：`3-业务线/Gitea知识库/tasks.md` +- 资源：`3-业务线/Gitea知识库/resources.md` +- 决策：`3-业务线/Gitea知识库/decisions.md` +- 操作记录：`3-业务线/Gitea知识库/operation-log.md` +- 后续专题设计与实施记录：在本目录下按明确产物建立，不预建占位目录 + +## 当前完成标准 + +`C0 工程设计构建` 的 v1.1 口径更新已完成，G0 中的 Gitea 本地基础服务与 MySQL 数据库初始化也已完成。当前完成口径为“固定版本安装、systemd 托管、localhost 监听、MySQL 迁移、安装锁、安全密钥、配置权限收紧和健康检查”；管理员、域名/HTTPS、反向代理、备份恢复、账号权限、试点仓库、MCP/身份/审计链路和业务发布仍未完成，因此尚未生产投用。代码开发仍需 Verlit 独立授权。 + +## 最近进展 + +- 2026-08-05：完成业务线建档并索引现有方案；搭建与部署明确暂缓。 +- 2026-08-06：移除无关的跨业务线排期与边界记录，后续仅按本业务线自身条件推进。 +- 2026-08-06：将原始 v1 归位为正式设计基线，纠正重新打开冻结模型、同步化和批量迁移化的任务偏移。 +- 2026-08-07：补充企业内部 AI 的 Context 与权限治理底座定位，明确只读 Agent 属于 v1，身份与受控 Skill 为后续扩展。 +- 2026-08-07：完成方案包与 EXE 执行单逐项分类，形成设计追溯、实施参数清单、详细实施方案和验收止损矩阵。 +- 2026-08-07：纠正“试点参数是当前阻塞点”的阶段表达，完成工程构建规格和 DEV-00～14 开发任务分解；当前无需试点或服务器参数，代码开发与真实实施均未开始。 +- 2026-08-10：根据全员 Agent 工作方式新增 v1.1 差量设计，确认 MCP 为唯一用户业务入口、飞书登录绑定内部主体、内部权限＋Gitea 权限双层限制、逐调用三主体强制审计，并明确不建设自定义业务 Web；同步更新工程、开发、实施和验收文档，仍未进入代码或真实实施。 +- 2026-08-10：形成 Go 1.26＋官方 Go MCP SDK＋PostgreSQL 18＋Gitea 1.26 的推荐技术基线，拆解 C1-00～12 与 G0～G5；识别 Agent Host 的逐用户 OAuth、精确确认和本地文件传输为开工前硬门。 +- 2026-08-10：确认 Agent 品牌不进入核心架构，由自有兼容框架优先适配 Codex、Claude Code；逐用户 MCP OAuth、人类确认和可控本地文件传输已具备方向，改以统一 adapter contract 和 Local Source Gate 验收。 +- 2026-08-10：完成闭环缺口审查，补齐成熟 OAuth/OIDC Authorization Server 边界、受控飞书—Gitea 预配置绑定和 PostgreSQL `pg_trgm` 中文检索基线；形成完整 PRD 与 Obsidian Canvas，逐步标注调用、功能、输出、审计、拒绝、撤权、重试和恢复回路。 +- 2026-08-11：Verlit 明确授权进入范围受限的 G0 基础实施；在共享主机 `120.27.248.208` 安装并验证 Gitea 1.26.4，仅监听 `127.0.0.1:3000`。未修改 `/www/wwwroot/gitea` 源码、宝塔/Nginx、防火墙、Redis 或其他业务；数据库、反代、域名、备份、仓库和权限仍待后续单独配置。 +- 2026-08-11：在 Verlit 完成 MySQL 参数与 `INSTALL_LOCK=true` 配置后，生成 `SECRET_KEY`/`INTERNAL_TOKEN`，仅重启 Gitea，完成 MySQL 自动迁移、主页与 `/api/healthz` 200 验证，并将 `/etc/gitea` 与 `app.ini` 权限收紧至 0750/0640；当前数据库内尚无用户。 +- 2026-08-11：创建首个管理员 `Verlit`，绑定用户指定邮箱，账号 active 且 IsAdmin=true；使用 24 位随机临时密码并要求首次登录修改，未创建访问令牌。 diff --git a/Gitea知识库/decisions.md b/Gitea知识库/decisions.md new file mode 100644 index 0000000..3ef0154 --- /dev/null +++ b/Gitea知识库/decisions.md @@ -0,0 +1,99 @@ +--- +type: decisions +owner: Verlit +last_updated_at: 2026-08-10 +last_updated_by: Codex +hash: sha256:c32b344a68c2e8bd3fb5398774841fcef35b280d751962d1e0a26872e50ccb84 +belongs_to: + - 3-业务线/Gitea知识库/_context +depends_knowledge: [] +--- + +# Gitea知识库决策记录 + +## 2026-08-05：建立独立业务线 + +- 决策：Gitea 知识库作为独立业务线管理，不以工具专题代替业务归属。 +- 原因：它有独立目的、边界、产物、资源、实施周期和风险模型。 +- 影响：Gitea 方案、决策、任务与实施记录只进入本业务线。 + +## 2026-08-05：实施保持在阶段 0 + +- 决策：当前先完成 Gitea 知识库的业务线入口、设计基线、工程规格、任务拆解和验收条件；代码开发、搭建、部署与业务知识发布均未开始。 +- 原因：整个项目仍处于构建设计阶段，尚未作出进入代码开发或真实实施的决定。 +- 进入下一阶段的条件：由 Verlit 明确宣布进入对应阶段；参数准备本身不会触发开发或实施。 +- 当前允许：本地设计、规格和任务整理；不创建代码仓库，不编写或运行系统代码，不执行远端动作。 + +## 2026-08-06：确认 v1 设计真源 + +- 决策：`公司共享 Context 项目仓库发布方案 v1` 是本业务线当前设计基线，正文 hash 保持 `sha256:a3a33cec7dfd0441fdf12af420bfc4f3d63ee7c113d4ae298ab96d2e2e45285f`。 +- 处理：文件从 `0-收集箱/` 归位到本业务线，原路径通过 `migrated_from` 保留。 +- 影响：后续复核只校验补充材料的一致性和版本关系，不重新打开主方案已经冻结的核心模型。 + +## 2026-08-06：恢复原方案冻结决策 + +- 项目是公司共享知识的业务容器，仓库是权限容器；v1 默认一项目一私有仓库。 +- 个人工作区保存原料、过程稿和个人历史；公司项目仓库只保存经过单向明确发布的共享产物。 +- 不同步整个私人 Vault，不做私人来源与企业 `current` 的双向同步，也不以批量迁移作为扩展方式。 +- 发布网关是受保护 `main` 的唯一写入者；普通成员和 Agent 不直接 push `main`。 +- `main/current` 是人和 Agent 的唯一默认读取面；历史、构建区和私人来源不进入默认 Context。 +- 技术状态使用 `current / superseded / retired`，内容状态使用 `discussion / confirmed`；进入 current 不等于已经定稿。 +- Agent 使用项目级只读身份，发布完成必须核对 Git、current、读取入口和 Agent 读回。 +- 试点审核策略固定为 `forced_off`；v1 不建设通用审批、PR/MR、多级会签或飞书权限集成。 +- 恢复旧版必须形成新的 current 发布，不能让不同成员长期停留在不同历史版本。 + +## 2026-08-06：限定未来实施开放问题 + +- 决策：进入未来真实实施前，只需补充首个试点、成员、维护者、发布者、服务器与 NAS 参数，以及可选驾驶舱决定。 +- 已冻结的仓库、权限、分支、发布、状态和回读模型不是待选项。 +- 进入远端实施前必须形成明确的风险、停止条件、回滚和验收清单。 + +## 2026-08-05：禁止隐式远端动作 + +- 决策：当前阶段不调用 Gitea、Git 远端、服务器、SSH、数据库或发布能力。 +- 原因：尚未进入有具体目标资源、责任人、备份和验收条件的实施任务。 + +## 2026-08-07：明确长期战略定位 + +- 决策：本业务线定位为企业内部 AI 的共享 Context 与权限治理底座，不扩张为承接所有企业 AI 产品形态的总业务线。 +- 阶段关系：先建立知识发布、授权、审计和恢复基础链路，并在 v1 接入只读 Agent；后续再扩展飞书身份映射、动态授权、受控 Skill 和更完整的 Agent 协同能力。 +- 语义边界：“先知识库、后 Agent”不表示 v1 没有 Agent，后置的是更高阶的 Agent 身份、权限和执行能力。 + +## 2026-08-07：分离工程设计、代码开发和真实实施 + +- 决策：使用 `C0 工程设计构建 → C1 代码开发准入 → G0 真实实施准入` 三个独立阶段。 +- 当前状态：C0 初版完成；C1 和 G0 均未开始、未授权。 +- 影响：试点、成员、服务器、备份和 RPO/RTO 从当前任务移入未来 G0，不再阻断 C0。 +- 授权边界：代码开发授权不包含部署；真实实施授权不由代码完成自动触发；每次阶段切换都必须由 Verlit 明确决定。 +- 架构影响：无。该决策只纠正任务阶段与授权表达，不改变 v1 主方案的仓库、发布、权限、current、状态或 Agent 模型。 + +## 2026-08-10：采用 v1.1 MCP-first 身份与强制审计覆盖层 + +- 决策：保留 `公司共享 Context 项目仓库发布方案 v1` 正文和 hash 不变，新增 `公司共享 Context MCP-first 身份与审计方案 v1.1` 作为差量覆盖层；v1.1 未明确覆盖的 v1 内容继续有效。 +- 用户入口：全员通过 Agent 工作，MCP 是唯一用户业务接口；生产目标为远程 MCP，STDIO 只用于本地开发；不建设自定义登录页、发布驾驶舱、权限后台或审计后台。 +- 身份：用户通过飞书登录绑定内部稳定 `UserIdentity`，再绑定 Gitea 账户；不以共享机器人身份承载所有人的行为，不在飞书/MCP/Gitea token 之间透传。 +- 权限：内部 `ProjectGrant` 是第一层，Gitea 项目权限复核是第二层；任一层拒绝均 fail closed，并记录不一致。 +- Agent：A1/A2 默认允许；A3/A4 可以代表已登录用户提交受控请求，但必须绑定项目、candidate hash、`base_current`、AgentSession 和精确人类确认，真正写 `main` 的仍是发布网关服务身份；A5 不暴露。 +- 审计：每次 MCP 调用由服务端自动记录 human＋agent＋service 行为链；审计查询可走只读 MCP，审计写入、更新和删除不作为普通工具。 +- 运维边界：部署、迁移、备份/恢复、密钥、Gitea Admin、权限写入、任意 SQL/SSH 和动作开关不暴露为普通用户 MCP 工具。 +- 后续版本：Skill Registry、飞书内容来源、通用审批和自定义业务 Web 仍不属于 v1.1。 +- 历史口径覆盖：2026-08-06 的“驾驶舱可选”和 2026-08-07 的“飞书身份/动态授权后置”只对原 v1 成立，已被本次 v1.1 决策覆盖；v1 原稿本身未被修改。 +- 当前执行边界：只更新本地设计与任务文档；没有创建代码、运行 MCP、连接飞书/Gitea、部署服务或写入远端。 + +## 2026-08-10：Agent 品牌与业务核心解耦 + +- 决策：Agent 类型不是业务架构依赖；由 Verlit 的兼容框架提供统一 adapter contract，首批优先适配 Codex 和 Claude Code。 +- 已确认：每位用户独立连接远程 MCP 并完成 OAuth；框架支持 A3/A4 人类确认；Agent 可以读取并传输本地文件，但必须经过控制门。 +- 信任边界：服务端不信任 Agent 自报的 user、role、session 或“用户已确认”；只信任 OAuth 验证主体和框架签发、绑定精确 request hash 的一次性 confirmation。 +- 本地内容：新增 Local Source Gate，固定允许根、明确选择、真实路径/符号链接、类型、大小、隐藏/控制文件、本地预检查、用户确认、manifest/hash、分块完整性和临时清理规则。 +- 影响：Codex、Claude Code 或其他 Agent 只增加适配器和兼容测试，不改变 MCP 工具、双层权限、发布事务、current 和审计核心。 +- 当前状态：完成设计修订，不代表 Codex/Claude Code adapter 已编码或测试。 + +## 2026-08-10：闭环安全与中文检索实现口径 + +- OAuth 边界：MCP OAuth 的授权服务器职责由成熟 OAuth/OIDC Authorization Server 承担，飞书作为员工身份联邦来源；`contextd` 是 MCP resource server 和业务策略服务，不从零自研完整授权服务器。 +- 绑定方式：飞书登录只证明人员身份；v1.1 试点由治理人员受控预配置飞书稳定 ID 与 Gitea 数字用户 ID，未绑定、冲突或停用均 fail closed。自报 Gitea username 不能产生授权。 +- 中文检索：首期使用 PostgreSQL `pg_trgm`＋标题、标签、相对路径和正文元数据过滤，并只索引 current；原生 FTS 不作为中文主检索，只有基准不达标才评审扩展。 +- 产品产物：以 `Gitea知识库 v1.1 产品需求文档 PRD.md` 作为当前组合设计的产品与实施需求视图，以 `Gitea知识库 v1.1 完整流程闭环.canvas` 作为逐步骤可视化；两者均从 v1＋v1.1 派生，不覆盖上游版本真源。 +- 版本影响：以上内容补齐实现责任和安全路径，不改变 v1 的仓库、发布、current、状态、恢复和止损原则，也不把 Skill Registry 纳入 v1.1。 +- 当前状态：仅完成本地文档和 Canvas；OAuth 产品、真实绑定名单、环境参数、代码、部署和试点均未开始。 diff --git a/Gitea知识库/operation-log.md b/Gitea知识库/operation-log.md new file mode 100644 index 0000000..0afa5da --- /dev/null +++ b/Gitea知识库/operation-log.md @@ -0,0 +1,82 @@ +--- +type: operation_log +owner: Verlit +last_updated_at: 2026-08-11 +last_updated_by: Codex +hash: sha256:551318f3f4d4429cf90c56b09f8306ae0a95c9e45de9ce53642ad5a13c75bfd8 +belongs_to: + - 3-业务线/Gitea知识库/_context +depends_knowledge: [] +--- + +# Gitea知识库操作记录 + +## 2026-08-05 + +- 根据 Verlit 的明确要求创建 `3-业务线/Gitea知识库/`。 +- 创建业务上下文、任务、资源、决策和操作记录五项基础文档。 +- 索引现有公司共享 Context 发布方案及配套方案包。 +- 明确当前仅完成业务线建档与方案索引，尚未进入实施阶段。 +- 未执行 Gitea 安装、服务器连接、仓库创建、权限调整、内容迁移、远端同步或发布。 + +## 2026-08-06 + +- 清理与本业务线目标无关的跨业务线排期、边界和启动条件记录。 +- 明确后续只依据 Gitea 知识库自身的试点范围、责任人、实施参数和验收条件推进。 +- 对照原始 `公司共享 Context 项目仓库发布方案 v1` 完成偏移审查。 +- 将主方案从 `0-收集箱/` 归位到本业务线，保留 `migrated_from`、原正文 hash 和治理补丁关系。 +- 将业务线阶段调整为“方案冻结与实施参数”，不再重新选择已冻结的仓库、权限、发布、`current` 和状态模型。 +- 将任务恢复为 Gitea 基础层、基础链路、发布入口、真实试点和 v2 判决五个后续阶段。 +- 清理“同步器”“批量迁移”和“重新确定模型”等偏移表述；未执行任何远端操作。 + +## 2026-08-07 + +- 在业务线上下文补充企业内部 AI 的共享 Context 与权限治理底座定位。 +- 明确知识库基础链路优先、只读 Agent 已属于 v1，飞书身份、动态授权和受控 Skill 为后续扩展。 +- 保持现有阶段和实施任务不变；未执行任何远端操作。 +- 逐份复核方案包 00～12 与执行落地手册 EXE-00～13，登记 adopted、补充、可选和已失效章节，不重新打开 v1 冻结决策。 +- 形成 `v1-设计追溯与版本关系.md`、`v1-实施参数与决策清单.md`、`v1-详细实施方案.md` 和 `v1-验收与止损矩阵.md`。 +- 明确当前 v1 不纳入飞书身份数据库和 Skill Registry；它们分别作为后续版本候选，不能成为 v1 实施前置。 +- 清除决策记录中遗留的跨业务线排期说明；Gitea 的暂停与启动条件只依据本业务线自身参数。 +- 本次只修改本地业务线文档，未连接服务器，未安装 Gitea，未创建仓库、账号或权限，未执行同步和发布。 +- 根据 Verlit 明确指令，将当前阶段纠正为 `C0 工程设计构建`，把代码开发和真实实施拆为需要分别授权的 `C1` 与 `G0`。 +- 将首个试点、成员、服务器、备份和 RPO/RTO 移到未来 G0，不再显示为当前推进阻塞项。 +- 新建 `v1-工程构建规格.md`，补齐逻辑模块、平台代码仓库与项目 Context 仓库分离、契约所有权、状态、逻辑操作、配置与秘密边界。 +- 新建 `v1-开发任务分解.md`，形成 DEV-00～14 及可选任务；全部保持 planned，未创建或修改任何代码。 +- 扩充 `v1-验收与止损矩阵.md`，增加 C0/C1/G0 阶段门与 CT/UT/IT/SEC/REC/T 六层测试规格。 +- 本轮仍只修改本地文档；未创建平台代码仓库，未编写或运行系统代码，未连接服务器/Gitea，未部署、未发布、未写入 `_runtime`。 + +## 2026-08-10 + +- 对照当前“全员 Agent＋MCP”目标复核 v1 的入口、身份、权限、Agent 和审计口径，确认底层仓库/发布/current 模型可继承，不需要重写完整设计。 +- 新建 `公司共享 Context MCP-first 身份与审计方案 v1.1.md`，以差量覆盖方式将 MCP 唯一用户入口、无自建 Web、飞书身份绑定、内部权限＋Gitea 权限双层限制、A3/A4 受控请求和三主体强制审计纳入当前目标。 +- 保持 `公司共享 Context 项目仓库发布方案 v1.md` 正文及 `sha256:a3a33cec7dfd0441fdf12af420bfc4f3d63ee7c113d4ae298ab96d2e2e45285f` 不变。 +- 同步更新工程构建规格、DEV-00～14、实施参数、EXE-01～12、验收止损、版本追溯、业务入口、任务、资源和决策。 +- 明确审计查询可走 MCP，但审计写入由服务端中间件自动完成；部署、迁移、备份、密钥、Gitea Admin、权限写入、SQL/SSH 和动作开关不暴露为普通 MCP 工具。 +- 本轮只修改本地 Markdown 设计文档；未创建代码仓库或代码，未运行 MCP/测试，未连接飞书、Gitea、服务器或其他远端，未部署、未发布、未写入 `_runtime`。 +- 根据 Verlit 要求补充 `v1.1-技术栈与详细实施设计.md`，推荐 Go 1.26.x、官方 Go MCP SDK v1.7.x、PostgreSQL 18.x、Gitea 1.26.x、`net/http`、pgx/sqlc、PostgreSQL outbox/检索和 OCI 打包。 +- 设计采用模块化单体代码库、`serve/worker` 双运行角色，不引入自定义 Web、Redis、Kafka、Elasticsearch、向量数据库、微服务或 Kubernetes 前置。 +- 将 Agent Host 的逐用户远程 MCP OAuth、可靠 A3/A4 确认和本地 Markdown 读取/传输定义为 C1-00 硬门；未验证前不声称真实身份和发布工具可用。 +- 根据 Verlit 补充信息，将 Agent Host 硬门重构为 Agent 无关的 adapter contract：首批 Codex、Claude Code，后续客户端只新增适配器。 +- 确认逐用户远程 MCP OAuth、框架人类确认和本地文件读取/传输方向成立；新增 Local Source Gate，限制允许根、明确选择、类型/大小、路径逃逸、控制文件、预检查、manifest/hash 和分块完整性。 +- 明确客户端原生 tool prompt 只作为交互保护，服务端发布授权仍要求框架签发的一次性 confirmation；本轮未运行 Codex/Claude Code MCP 连接或任何代码。 +- 完成闭环缺口审查：将 MCP OAuth 协议与令牌生命周期边界固定为成熟 OAuth/OIDC Authorization Server＋飞书身份联邦；将首次绑定固定为飞书稳定 ID 与 Gitea 数字 ID 的受控预配置；将中文主检索从 PostgreSQL 原生 FTS 修正为 `pg_trgm`＋元数据过滤。 +- 新建 `Gitea知识库 v1.1 产品需求文档 PRD.md`，覆盖产品范围、角色、S00～S28 调用/功能/输出、MCP 工具、状态、安全默认值、异常、验收、开发/实施分段和未决 Gate。 +- 新建 `Gitea知识库 v1.1 完整流程闭环.canvas`，以 Obsidian Canvas 表达登录、双层授权、读取、来源、构建、发布、current、检索、读回、审计、拒绝、撤权、重试和恢复闭环。 +- 本轮仍只生成和修订本地设计产物；未安装额外能力，未编写/运行系统代码，未连接飞书/Gitea/服务器，未部署或发布。 + +## 2026-08-11 + +- Verlit 明确授权进入范围受限的 G0 基础实施，目标主机为 `120.27.248.208`、SSH 范围为 `/`；同时明确不得变动服务器上其他正在运行的代码与服务，反向代理由 Verlit 自行处理。 +- 只读核对 `/www/wwwroot/gitea`，确认其为 Gitea 源码检出而非运行安装目录；本次未构建、修改或运行该源码，验收时 tracked 状态为空，HEAD 为 `7e3eeca7795db95f25c14174855c1ac12e8797e5`。 +- 为 SSH MCP 增加仅限固定主机、`gitea_base` profile 和 `/www/wwwroot/gitea` 的白名单安装/检查能力；本地 9 项测试及 MCP 配置校验通过。 +- 下载官方 Gitea 1.26.4 Linux amd64 二进制，使用官方签名主密钥指纹 `7C9E68152594688862D62AF62D9AE806EC1592E2` 验证二进制与校验和签名，并核对 SHA-256 `0faa36d151918f8f7d6e0f3ae67597d1c338583d695add146ac393109d0fc44a`。 +- 新增独立 `git` 系统账号、`/usr/local/bin/gitea`、`/etc/gitea/app.ini`、`/var/lib/gitea` 和 `gitea.service`；服务仅监听 `127.0.0.1:3000`，systemd active，本机 HTTP 返回 200。 +- 未配置数据库、正式域名、HTTPS、反向代理、备份、组织、用户、仓库或权限；`INSTALL_LOCK=false`，当前只提供本机安装页。 +- 未修改宝塔/Nginx、防火墙、Redis、PHP 或其他业务。只读核对发现 `nginx.service` 的 failed 状态始于 2026-05-13，明显早于本次安装；宝塔 Nginx 进程仍监听 80/443，未对其执行任何处置。 +- 脱敏验收证据写入 `_runtime/gitea-install/snapshots/2026-08-11/base-install.md`。 +- Verlit 随后自行填写 Gitea 专用 MySQL 参数并设置 `INSTALL_LOCK=true`。脱敏核对确认必填项与密码均已填写，但未输出密码。 +- 因 `SECRET_KEY` 与 `INTERNAL_TOKEN` 缺失，为 Gitea 生成随机安全密钥；将原配置备份到 `/etc/gitea/app.ini.pre-finalize-20260811`（root:root、0600），再仅重启 `gitea.service`。 +- Gitea 完成 MySQL 自动迁移，主页与 `/api/healthz` 均返回 200；`/etc/gitea` 收紧为 0750，`app.ini` 收紧为 root:git、0640。 +- 只读查询确认数据库内尚无 Gitea 用户；下一步需创建首个管理员，再配置正式 `ROOT_URL` 与反向代理。 +- 根据 Verlit 指定的用户名与邮箱创建首个管理员；服务器端生成 24 位随机临时密码，设置 `--must-change-password`，未生成访问令牌。回读确认 ID=1、active=true、admin=true、2FA=false。 diff --git a/Gitea知识库/resources.md b/Gitea知识库/resources.md new file mode 100644 index 0000000..443346a --- /dev/null +++ b/Gitea知识库/resources.md @@ -0,0 +1,72 @@ +--- +type: resources +owner: Verlit +last_updated_at: 2026-08-11 +last_updated_by: Codex +hash: sha256:fbd28ca90f70cbdb116f04486863d346c16ffca58963037df626b4591e8a9936 +belongs_to: + - 3-业务线/Gitea知识库/_context +depends_knowledge: [] +--- + +# Gitea知识库资源索引 + +## 设计与证据资源 + +| 资源 | 位置 | 当前定位 | 状态 | +|---|---|---|---| +| 公司共享 Context 项目仓库发布方案 v1 | `3-业务线/Gitea知识库/公司共享 Context 项目仓库发布方案 v1.md` | 业务目标、核心架构、冻结原则、试点和实施阶段的设计基线 | `published + confirmed`，当前设计真源 | +| 公司共享 Context MCP-first 身份与审计方案 v1.1 | `3-业务线/Gitea知识库/公司共享 Context MCP-first 身份与审计方案 v1.1.md` | 覆盖 MCP 唯一入口、飞书身份绑定、双层权限、Agent 受控动作、强制审计和无自建 Web | `draft + discussion`，当前目标差量覆盖层 | +| 公司共享 Context 发布与 AI 协同框架方案包 | `0-收集箱/临时待归属/2026-08-03-公司共享Context发布与AI协同框架/` | 接口契约、权限、安全、运维和 EXE 执行单的详细补充 | 已封板补充材料，版本关系已登记 | +| v1 审核开关治理模型 | `0-收集箱/临时待归属/2026-08-03-v1审核开关治理模型_deepseek-v4-pro.md` | `forced_off / forced_on / switchable` 审核语义 | 审核语义真源 | +| v1 最终方案一致性校验 | `0-收集箱/临时待归属/2026-08-03-v1最终方案一致性校验_codex.md` | 主方案、方案包和治理补丁的封板证据 | 一致性证据 | +| 历史合规与架构审查 | `0-收集箱/临时待归属/` 中的相关审查文件 | 记录问题发现、反馈和收敛过程 | 历史证据，不覆盖终版基线 | + +## v1.1 工程与未来实施基线产物 + +| 产物 | 位置 | 用途 | 当前状态 | +|---|---|---|---| +| v1/v1.1 设计追溯与版本关系 | `3-业务线/Gitea知识库/v1-设计追溯与版本关系.md` | 固定 v1 基线、v1.1 覆盖层、详细设计和 EXE 的采用关系 | v1.1 已更新；待随版本决策维护 | +| v1.1 工程构建规格 | `3-业务线/Gitea知识库/v1-工程构建规格.md` | 固定模块、逻辑仓库、MCP/身份/审计契约、配置安全和构建边界 | C0 v1.1 已完成；未创建代码仓库 | +| v1.1 技术栈与详细实施设计 | `3-业务线/Gitea知识库/v1.1-技术栈与详细实施设计.md` | 推荐 Go＋官方 MCP SDK＋PostgreSQL＋Gitea，定义 Codex/Claude Code adapter、Local Source Gate、C1 和 G0～G5 | Agent 架构 P0 已确认；等待客户端版本测试和环境 P1/P2 参数 | +| v1.1 产品需求文档 PRD | `3-业务线/Gitea知识库/Gitea知识库 v1.1 产品需求文档 PRD.md` | 固定产品范围、角色、S00～S28 调用/功能/输出、工具、状态、安全默认值、异常、验收和实施 Gate | `review-ready + discussion`；未授权开发/实施 | +| v1.1 完整流程闭环 Canvas | `3-业务线/Gitea知识库/Gitea知识库 v1.1 完整流程闭环.canvas` | 在 Obsidian 中展示登录、双层授权、读取、来源、构建、发布、current、读回、审计、撤权和恢复闭环 | 已整体放宽分组、节点间连线通道与上下流程间距并完成结构校验；图内回链 PRD/v1；文件 `sha256:427b3edea89d047982fcd272585a8e648474b42ea17883c06d1380121595af2a` | +| v1.1 开发任务分解 | `3-业务线/Gitea知识库/v1-开发任务分解.md` | 将未来代码开发拆为 DEV-00～14 与后续任务 | 已更新；全部为 planned，未授权开工 | +| v1.1 实施参数与决策清单 | `3-业务线/Gitea知识库/v1-实施参数与决策清单.md` | 记录未来 C1/G0 的 MCP、身份、审计和环境参数 | 已更新；open 项不是当前待办 | +| v1.1 详细实施方案 | `3-业务线/Gitea知识库/v1-详细实施方案.md` | 按 EXE-01～EXE-12 拆解依赖、步骤、产物、验收和回滚 | v1.1 环境无关部分已完成 | +| v1.1 验收与止损矩阵 | `3-业务线/Gitea知识库/v1-验收与止损矩阵.md` | 固定阶段门、六层测试、M01～M10、T01～T12、硬指标和止损 | C0 规格已形成；测试尚未运行 | + +## 真源优先级 + +1. `公司共享 Context MCP-first 身份与审计方案 v1.1.md`：对明确列出的入口、身份、权限、Agent 和审计事项优先。 +2. `公司共享 Context 项目仓库发布方案 v1.md`：其余业务目标、核心原则、仓库、发布事务、current 和状态基线。 +3. 审核开关治理模型：只覆盖 confirmed release 的条件审核语义。 +4. 发布与 AI 协同框架方案包及最终一致性校验：补充接口、安全、运维和执行细节。 +5. 历史评审、外部案例和调研：作为证据，不直接成为当前实施口径。 + +v1.1 未明确覆盖的 v1 事项继续有效；补充材料冲突时必须先形成明确版本决策，不得静默替换冻结基线。 + +## Gitea 基础运行资源 + +| 资源 | 位置 | 当前定位 | 状态 | +|---|---|---|---| +| 目标主机 | `120.27.248.208` | Gitea 知识库业务与其他业务共享的服务器 | 已完成只读盘点；不得改动其他业务 | +| 源码检出 | `/www/wwwroot/gitea` | 现有 Gitea 源码仓库，仅用于识别版本与上下文 | commit `7e3eeca7795db95f25c14174855c1ac12e8797e5`；本次未写入 | +| Gitea 二进制 | `/usr/local/bin/gitea` | 官方固定版本运行制品 | 1.26.4；官方签名与 SHA-256 已验证 | +| Gitea 配置 | `/etc/gitea/app.ini` | 本地监听、MySQL 与安全配置真源 | 仅监听 `127.0.0.1:3000`；MySQL 已配置，安装锁已关闭，0640 | +| Gitea 数据 | `/var/lib/gitea` | custom、data、log 运行目录 | `git:git`、0750；尚无正式仓库数据 | +| Gitea 服务 | `/etc/systemd/system/gitea.service` | systemd 托管单元 | enabled + active；运行用户/组均为 `git` | +| 安装验收证据 | `_runtime/gitea-install/snapshots/2026-08-11/base-install.md` | 脱敏安装与只读回验记录 | 已生成 | + +## 当前资源状态 + +- 正式 v1 设计基线：已归位到本业务线； +- v1.1 MCP-first 身份与审计覆盖层：已形成并同步到执行文档； +- 补充方案版本关系：一级真源关系和逐文档采用状态均已登记； +- C0 工程设计构建：v1.1 模块、逻辑仓库、推荐技术栈、完整 PRD、Canvas 闭环图、开发任务、测试、参数、验收和止损基线已形成； +- C1 代码开发：未授权，平台代码仓库未创建，DEV-00～14 均未开工； +- G0 真实实施：已获范围受限的 Gitea 基础安装授权；试点、成员、飞书身份应用、远程 MCP、身份/审计存储、备份、RPO/RTO 和应急责任仍未确认； +- Gitea 服务：1.26.4 已搭建，仅监听 `127.0.0.1:3000`，MySQL 迁移及健康检查通过，首个管理员已创建，正式域名未配置； +- 实现代码库：未建立； +- 试点仓库：未创建； +- 远端资源：仅新增 Gitea 自身运行资源；未修改现有业务代码、宝塔/Nginx、防火墙、Redis 或其他业务服务。 diff --git a/Gitea知识库/tasks.md b/Gitea知识库/tasks.md new file mode 100644 index 0000000..8585653 --- /dev/null +++ b/Gitea知识库/tasks.md @@ -0,0 +1,133 @@ +--- +type: tasks +owner: Verlit +last_updated_at: 2026-08-11 +last_updated_by: Codex +hash: sha256:1d348609d6a7a464a69599c921493fd3e44a14f7122c30a01fd7bfdfd5e9bff4 +belongs_to: + - 3-业务线/Gitea知识库/_context +depends_knowledge: [] +--- + +# Gitea知识库任务清单 + +## 当前阶段说明 + +- 当前阶段：`C0` 设计已完成；Verlit 已明确授权进入范围受限的 `G0` 基础实施。 +- 已完成：目标主机上的 Gitea 1.26.4 基础安装、systemd 托管、`127.0.0.1:3000` 本地监听和 HTTP 验证。 +- 当前待配置：正式域名/HTTPS、反向代理、备份、细分账号权限和试点仓库。 +- 当前禁止：改动共享主机上的其他业务代码、宝塔/Nginx、防火墙、Redis、PHP 或复用其他业务数据库；平台代码开发也仍未授权。 +- 后续数据库、公开访问、试点与代码开发均需要按各自范围继续推进，不能从本次基础安装自动推导。 + +## P0：业务线与 v1 基线归位（已完成） + +- [x] 创建 Gitea 知识库独立业务线。 +- [x] 索引公司共享 Context 项目仓库发布方案及配套方案包。 +- [x] 将 `公司共享 Context 项目仓库发布方案 v1` 从收集箱归位到本业务线，并保留原路径与正文 hash。 +- [x] 确认主方案是当前设计基线，不重新打开已经冻结的仓库、权限、发布、`current` 和状态模型。 +- [x] 纠正“同步器”“批量迁移”“重新确定模型”等偏移表述。 +- [x] 明确当前不执行安装、部署、远端创建、权限调整或内容发布。 + +## P1：C0 工程设计构建（当前，已完成） + +- [x] 建立主方案、审核开关治理基线、最终一致性校验、执行方案包和历史审查材料的一级版本关系。 +- [x] 清点方案包内逐份文档，标记采用、补充、历史或废弃状态，不重新打开主方案冻结决策。 +- [x] 建立设计追溯矩阵，将 v1 冻结原则映射到详细设计、EXE 执行单和验收证据。 +- [x] 按 EXE-01～EXE-12 编制逐步骤实施方案，明确依赖、输入、动作、产物、验收和停止条件。 +- [x] 建立工程构建规格，固定模块、逻辑仓库、依赖、契约、配置和秘密边界。 +- [x] 建立 DEV-00～14 开发任务包，明确依赖、交付物、测试映射、完成和停止条件。 +- [x] 将验收矩阵补充为 CT/UT/IT/SEC/REC/T 六层测试规格。 +- [x] 建立实施参数与决策清单，明确它是未来实施准入材料，不阻断当前构建设计。 +- [x] 形成实施风险、停止条件、回滚和验收矩阵。 +- [x] 新增 v1.1 MCP-first 身份与审计差量覆盖层，不修改 v1 原稿。 +- [x] 将 MCP 从可选适配器提升为唯一用户业务入口，并明确不建设自定义业务 Web。 +- [x] 将飞书登录绑定、内部稳定主体/Gitea 账户、双层权限和 AgentSession 纳入必需设计。 +- [x] 将逐次 MCP 调用的 human＋agent＋service 强制审计纳入工程、实施和验收。 +- [x] 将工程构建、开发任务、实施参数、详细实施和验收文档统一切换到 v1.1 口径。 +- [x] 形成 v1.1 推荐技术栈与详细实施设计，选择 Go＋官方 MCP SDK＋PostgreSQL＋Gitea 的默认基线，并定义 Agent 无关的 adapter contract。 +- [x] 完成闭环缺口审查，补齐成熟 OAuth/OIDC Authorization Server、飞书—Gitea 受控预配置绑定与 `pg_trgm` 中文检索基线。 +- [x] 形成 v1.1 完整 PRD 和 Obsidian Canvas，覆盖 S00～S28 的调用、功能、输出、审计、拒绝、撤权、重试和恢复回路。 +- [x] 更新业务线入口、任务、资源和操作记录，并完成正文 hash 与一致性校验。 + +当前组合设计不在本阶段重新选择：v1 的一项目一私有仓库、单向明确发布、发布网关唯一写 `main`、`main/current` 唯一默认读取面、`discussion / confirmed` 内容状态和试点 `forced_off`；v1.1 的 MCP 唯一用户入口、飞书身份绑定、内部权限＋Gitea 权限双层限制、A3/A4 受控网关请求、三主体强制审计和无自建 Web。 + +## P2：C1 代码开发准入（未来，未授权） + +- [ ] 由 Verlit 明确宣布进入代码开发；没有该决定时 DEV 任务保持 `planned`。 +- [ ] 确认平台代码仓库的正式归属、名称、维护者和验收人。 +- [ ] 确认运行时、编程语言、MCP SDK/协议、最低版本、依赖和制品策略；不选择自建 Web 前端框架。 +- [ ] 在 C1-04 前确认可复用或独立部署的成熟 OAuth/OIDC Authorization Server；不得在业务服务内临时自研完整授权服务器。 +- [x] 确认 Agent 接入原则：框架兼容不同 Agent，优先 Codex、Claude Code；每人独立远程 MCP OAuth，支持人类确认和受控本地文件传输。 +- [ ] 先执行 `v1.1-技术栈与详细实施设计.md` 的 C1-00，固定 Codex/Claude Code 支持版本并通过统一 adapter contract。 +- [ ] 确认飞书登录真实配置、受控飞书—Gitea 预配置绑定、身份权限库和 audit store 的环境技术参数。 +- [ ] 确认开发仅使用合成身份/数据、fake adapter 和临时目录，不连接真实飞书或 Gitea。 +- [ ] 依次执行 `v1-开发任务分解.md` 中 DEV-00～14，并按测试映射验收。 +- [ ] 形成可复现、无秘密、不会自动连接环境的开发制品。 + +代码开发准入不包含服务器部署、真实账号、项目仓库创建和试点授权。 + +## P3：G0 实施准入（已进入，部分条件明确） + +- [x] 由 Verlit 明确宣布进入实施；本轮仅授权 Gitea 基础安装与 localhost 验证。 +- [x] 确认目标主机 `120.27.248.208` 与 SSH 范围 `/`；远端写入仍收窄到 Gitea 自身资源。 +- [ ] 确认首个正在运行、确实需要共享 Context 的低敏感项目（D03）。 +- [ ] 确认实际项目成员，不默认全员授权（D04）。 +- [ ] 指定项目维护者、至少一名 publisher、治理身份和应急责任（D05/D16）。 +- [ ] 确认目标服务器的 OS、网络、域名/HTTPS、磁盘、维护窗口和 NAS 备份路径（D12）。 +- [ ] 确认 RPO/RTO 和恢复验收口径（D15）。 +- [ ] 确认飞书身份应用/OAuth Authorization Server、远程 MCP 地址与认证、真实用户绑定范围。 +- [ ] 确认身份权限数据库、audit store、保留期限、脱敏规则和安全责任人。 +- [ ] 确认 Gitea 账户绑定、权限复核、缓存失效和撤权验证方式。 +- [x] 自定义发布驾驶舱已在 v1.1 关闭，不作为待选项。 +- [ ] 为每个远端动作明确目标、责任人、授权、回滚、验收和证据位置。 + +## P4：G1～G2 Gitea 基础实施（进行中，仅基础安装完成） + +- [x] 盘点目标服务器 OS、CPU/内存/磁盘、端口 3000、Git/GPG、容器环境和现有业务边界。 +- [x] 安装固定版本 Gitea 1.26.4，使用独立 `git` 系统账号、`/var/lib/gitea` 数据目录与 `gitea.service`，仅监听 `127.0.0.1:3000`。 +- [x] 验证 Gitea 服务 active、本机 HTTP 200、源码目录 tracked 状态干净，并记录脱敏运行证据。 +- [x] 配置独立 MySQL 数据库，生成安全密钥，完成自动迁移、安装锁、配置权限收紧和重启验证。 +- [x] 创建首个 active 管理员 `Verlit`，设置随机临时密码与首次登录强制修改。 +- [ ] 配置正式域名/HTTPS 与反向代理（由 Verlit 处理），再将 `ROOT_URL` 更新为正式地址。 +- [ ] 完成数据库、配置和仓库数据的异机备份与恢复验证，达到完整加固口径。 +- [ ] 建立独立账号、SSH key、项目团队和一个试点私有仓库。 +- [ ] 保护 `main`，只允许发布网关身份写入。 +- [ ] 建立仓库、数据库、配置和关键凭据材料的异机备份，并验证一次恢复。 +- [ ] 验证成员撤权后未来访问被阻止。 + +## P5：G3 项目仓库到 MCP current 读取链路（未来，未开始） + +- [ ] 按原方案建立 `README.md`、`current/`、`schema/` 和 `.gitignore`。 +- [ ] 从指定 commit 构建 staging，校验后原子切换唯一 `current`。 +- [ ] 建立按项目隔离的内部只读端口，并通过 Context Reader MCP 暴露用户读取能力。 +- [ ] 绑定飞书登录用户、内部 ProjectGrant、Gitea 账户权限和 AgentSession。 +- [ ] 验证人和 Agent 读取同一 release ID、hash 和 `content_status`。 +- [ ] 验证未授权项目、构建区、私人来源和 Git 历史不进入默认读取面。 + +## P6：G3 发布入口（未来，未开始） + +- [ ] 实现本地 Markdown 文件、章节和多材料的明确选择与 selection manifest。 +- [ ] 实现发布物构建、附件收集、链接改写、内容 hash 和 diff。 +- [ ] 实现结构、链接、路径、凭据、隐私和控制文件检查。 +- [ ] 实现发布网关的身份校验、幂等、`base_current` 并发阻断和受保护 `main` 提交。 +- [ ] 实现远程 MCP 用户工具面，A3/A4 必须绑定精确确认；MCP 不持有 Git 写凭据。 +- [ ] 实现服务端自动三主体审计和 outbox/等价可靠写入；审计写入/删除不暴露为普通工具。 +- [ ] 生成发布回执，并完成 Git、current、只读入口和 Agent 四段读回。 + +## P7：G4～G5 真实试点（未来，未开始） + +- [ ] 完成 `v1-验收与止损矩阵.md` 的 M01～M10 和 T01～T12。 +- [ ] 验证发布、读取、纠错、撤权、恢复发布和空环境恢复。 +- [ ] 确认普通成员无需处理 Git 分支、PR/MR 和复杂冲突。 +- [ ] 确认没有两个 current、私人内容泄漏、共享账号或不可恢复备份等止损信号。 +- [ ] 用真实成员使用结果完成试点验收，而不是以“软件已安装”代替验收。 + +## P8：v2 判决（未来，未开始） + +- [ ] 根据 v1.1 真实摩擦决定是否增加正式审批、Skill Registry、飞书内容来源、自定义 Web 或跨项目能力。 +- [ ] 没有真实使用证据的增强项不进入 v2。 +- [ ] 允许选择保持轻量 v1，不把 v2 当作必然扩建。 + +## 当前推进点 + +P1 的 v1.1 本地工程设计构建已完成，Verlit 已在 2026-08-11 明确授权进入范围受限的 G0 基础实施。Gitea 1.26.4 已通过 MySQL 自动迁移并在本地健康运行，首个管理员已创建；域名/HTTPS、反代、备份、细分账号权限和试点仓库尚未完成，P2 平台代码开发仍未授权。下一推进点是由 Verlit 配置反向代理并更新正式 `ROOT_URL`。 diff --git a/Gitea知识库/v1-实施参数与决策清单.md b/Gitea知识库/v1-实施参数与决策清单.md new file mode 100644 index 0000000..61a903e --- /dev/null +++ b/Gitea知识库/v1-实施参数与决策清单.md @@ -0,0 +1,173 @@ +--- +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 代码开发准入`，不自动获得任何真实环境权限。 diff --git a/Gitea知识库/v1-工程构建规格.md b/Gitea知识库/v1-工程构建规格.md new file mode 100644 index 0000000..36e156d --- /dev/null +++ b/Gitea知识库/v1-工程构建规格.md @@ -0,0 +1,358 @@ +--- +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 +/ +├─ 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 +-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、真实账号和试点项目继续由未来实施准入门控制。 diff --git a/Gitea知识库/v1-开发任务分解.md b/Gitea知识库/v1-开发任务分解.md new file mode 100644 index 0000000..6f06d88 --- /dev/null +++ b/Gitea知识库/v1-开发任务分解.md @@ -0,0 +1,367 @@ +--- +title: Gitea知识库 v1.1 开发任务分解 +date: 2026-08-07 +type: tasks +status: draft +content_status: discussion +owner: Verlit +last_updated_at: 2026-08-10 +last_updated_by: Codex +hash: sha256:6d1468c5dae4cb8efcb80cda34d952106018a0b7db0f47054f18a3fab9f43a49 +hash_scope: Markdown 正文（从一级标题开始至文件末尾）的 UTF-8 SHA-256 +belongs_to: + - "[[3-业务线/Gitea知识库/_context|Gitea知识库]]" +depends_knowledge: + - "[[3-业务线/Gitea知识库/v1-工程构建规格|v1 工程构建规格]]" +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 验收与止损矩阵]]" +--- + +# Gitea知识库 v1.1 开发任务分解 + +## 1. 使用边界 + +本文件是未来代码开发的可下发 backlog。当前只完成任务拆解，所有 `DEV-*` 均为 `planned`，没有创建代码仓库、编写代码、运行测试、连接 Gitea 或部署服务。 + +任务开工需同时满足：Verlit 明确宣布进入代码开发；平台代码仓库和技术栈已确认；任务有责任人、验收人、产物位置和停止条件。代码开发授权不自动包含服务器部署或真实试点授权。 + +## 2. 依赖总览 + +```mermaid +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//` 与唯一 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 更新责任。 + +未满足这些条件时，本文件保持规划状态，不能把“任务已拆解”解释为“代码已经开始开发”。 diff --git a/Gitea知识库/v1-设计追溯与版本关系.md b/Gitea知识库/v1-设计追溯与版本关系.md new file mode 100644 index 0000000..c75303d --- /dev/null +++ b/Gitea知识库/v1-设计追溯与版本关系.md @@ -0,0 +1,129 @@ +--- +title: Gitea知识库 v1/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:9236e755129218a1625125ecf2c6eaaeda81fc42838bebacf4d392ef66f4403a +hash_scope: Markdown 正文（从一级标题开始至文件末尾）的 UTF-8 SHA-256 +belongs_to: + - "[[3-业务线/Gitea知识库/_context|Gitea知识库]]" +source_refs: + - "3-业务线/Gitea知识库/公司共享 Context 项目仓库发布方案 v1.md" + - "3-业务线/Gitea知识库/公司共享 Context MCP-first 身份与审计方案 v1.1.md" + - "0-收集箱/临时待归属/2026-08-03-公司共享Context发布与AI协同框架/" +--- + +# Gitea知识库 v1/v1.1 设计追溯与版本关系 + +## 1. 目的 + +本文件固定 v1 主方案、v1.1 差量覆盖层、治理补丁、详细设计、执行单和历史审查之间的采用关系。它不创造新的架构，只回答每份材料进入哪个版本、哪些旧描述被覆盖，以及后续实施步骤应回溯到哪里。 + +```text +v1 冻结发布基线 + + v1.1 对入口、身份、权限、Agent 写请求和审计的明确覆盖 + = 当前目标设计 + → PRD（产品/功能/验收）＋Canvas（流程可视化）＋工程/实施执行文档 +``` + +文件名中保留 `v1-` 的执行文档作为稳定路由，不表示其正文仍停留在旧口径；正文标题、来源和 hash 共同声明当前采用 v1.1。 + +## 2. 真源优先级 + +1. `公司共享 Context MCP-first 身份与审计方案 v1.1.md`：只对其明确列出的入口、身份、权限、Agent 和审计事项具有覆盖优先级。 +2. `公司共享 Context 项目仓库发布方案 v1.md`：其余业务目标、仓库、发布事务、current、状态和试点基线真源，正文保持不可变。 +3. `v1审核开关治理模型_deepseek-v4-pro.md`：只覆盖 confirmed release 的审核开关语义，不改变唯一 current 和发布网关；Agent 能力按 v1.1 覆盖。 +4. `公司共享Context发布与AI协同框架/`：接口、权限、安全、运维和执行细节补充。 +5. `v1最终方案一致性校验_codex.md`：证明 v1 材料在 2026-08-03 时的一致性，不证明后续 v1.1 覆盖项。 +6. 其他架构与合规审查：保留问题发现和收敛历史，不覆盖当前版本真源。 + +任何补充材料与 v1/v1.1 当前组合冲突时，默认停止采用冲突部分；只有形成新的业务线版本决策后才能改变当前目标。v1.1 未明确覆盖的事项不得自行推断为改变 v1。 + +`Gitea知识库 v1.1 产品需求文档 PRD.md` 和 `Gitea知识库 v1.1 完整流程闭环.canvas` 是当前组合设计的派生消费视图：前者承载完整需求、S00～S28、默认值和 Gate，后者承载同一流程的可视化。它们不能反向覆盖 v1/v1.1；发现冲突时必须回到上游版本决策修正。 + +## 3. 详细设计文档分类 + +| 文档 | 分类 | v1 采用结论 | 需要修正或限定的旧描述 | +|---|---|---|---| +| 00 项目入口与文档地图 | adopted-with-notes | 采用文档地图、冻结原则和阅读顺序 | “临时归属、不是正式业务线真源”已失效；正式业务线现为 `Gitea知识库` | +| 01 总体架构与模块边界 | adopted | 四个平面、独立模块和契约连接全部采用 | “需要用户设计”的事项只能补实现参数，不能重开一项目一仓、唯一 current 等冻结决定 | +| 02 分阶段实施计划与验收门 | adopted | 阶段和验收门采用 | 业务归属与 C0 工程设计已完成；试点与环境参数留到未来 G0，不是当前待办 | +| 03 来源接入选择与内容构建 | adopted-with-scope | 本地 Markdown 选择、构建、附件和链接规则采用 | v1.1 只使用飞书身份；飞书内容来源仍不进入当前目标 | +| 04 发布事务版本存储与只读分发 | adopted | 状态机、CAS、幂等、原子导出、恢复和读回采用 | 事务编排技术选型仍待实现阶段决定 | +| 05 MCP 工具路由与外部系统连接 | adopted-v1.1 | MCP 工具门禁、服务端复核和无高权回退采用 | “MCP 可选、HTTPS/CLI 为用户入口”已被 v1.1 覆盖 | +| 06 分层身份权限与凭据模型 | adopted-v1.1 | 飞书绑定内部用户、Gitea 绑定、双层授权、AgentSession 和服务身份采用 | 不建设通用企业管理系统，不透传三类 token | +| 07 业务线归属内容状态与流转 | adopted-with-superseded-sections | 内容状态、责任和 Agent 路由采用 | 第 7 节临时归属流程及第 8 节业务线选择问题已完成或失效 | +| 08 AI 权限控制与人机协同 | adopted-v1.1 | A0～A5、角色隔离、控制面隔离和输出规则采用 | A1/A2 默认；A3/A4 经用户绑定 MCP、精确确认和网关受控开放 | +| 09 安全隐私审计与事故响应 | adopted-v1.1 | 威胁模型、强制逐调用三主体审计和事故分级采用 | 审计查询可走 MCP；审计写入/删除不得成为普通工具 | +| 10 运行观测备份恢复与连续性 | adopted | 指标、告警、备份范围、恢复和降级采用 | SLO、RPO、RTO 是建议值，需用户确认后才成为承诺 | +| 11 接口契约数据模型与事件 | adopted-with-sample-fixes | 七类契约、错误和事件采用 | 样例中的 `business_line_id: temporary` 必须改为正式稳定 ID；`project_id` 待试点确认 | +| 12 试点方案决策清单与路线图 | adopted-with-status-fixes | Gate 0～5、试点范围、测试和止损采用 | D01 已完成、D02 已确认；成功标准中的“11 类样本”应为 12 类 | + +## 4. 执行单分类 + +| 执行单 | 分类 | 当前状态 | 进入条件 | +|---|---|---|---| +| EXE-00 执行总览 | adopted | 已采用 | 作为总索引，不单独执行 | +| EXE-01 业务归属与试点 | future-implementation-gate | 业务线和 owner 已确认；EXE 尚未启动 | Verlit 明确进入实施后，再确认试点、成员、角色、服务器和证据落点 | +| EXE-02 契约与状态机 | adopted | blocked-by-parameters | 稳定 business_line_id、project_id 和正式代码库 | +| EXE-03 Gitea 基础层 | adopted | blocked-by-target | 指定服务器、网络、管理员、备份目标及远端执行授权 | +| EXE-04 身份角色权限 | adopted-v1.1 | local-design-ready | 飞书/内部/Gitea 绑定、双层权限和会话进入必需链；真实账号/数据库等待 C1/G0 对应授权 | +| EXE-05 来源选择与构建 | adopted | blocked-by-contracts | EXE-02、正式代码库和来源规则完成 | +| EXE-06 质量安全检查 | adopted | blocked-by-builder | EXE-02、EXE-05 和策略责任人完成 | +| EXE-07 发布网关 | adopted | blocked-by-foundation | EXE-02、03、04、06 通过 | +| EXE-08 current 导出 | adopted | blocked-by-gateway | EXE-03、EXE-07 通过 | +| EXE-09 MCP Gateway | required-v1.1 | blocked-by-identity-and-core | EXE-04、07、08 通过；生产远程 MCP，开发 STDIO；不建设自定义 Web | +| EXE-10 Agent 读取与读回 | adopted-v1.1 | blocked-by-mcp | EXE-08 提供内部 read port，EXE-09 提供唯一用户工具面 | +| EXE-11 监控备份事故 | adopted | blocked-by-target | 随 EXE-03 启动，真实试点前必须完成 | +| EXE-12 试点与 v2 判决 | adopted | blocked-by-gates | EXE-01～11 中适用门禁通过 | +| EXE-13 下发与证据规范 | adopted | ready | 后续每个实施任务必须使用 | + +## 5. v1 基线与 v1.1 覆盖追溯矩阵 + +| 冻结原则 | 主方案依据 | 详细设计/执行消费者 | 验收证据 | +|---|---|---|---| +| 项目是业务容器，一项目一私有仓库 | 二、三、十 | 01、06、EXE-03/04 | 项目权限正反测试 | +| 个人材料单向明确发布，不做双向同步 | 二、六、十三 | 03、07、EXE-05 | selection 与未选内容测试 | +| 发布网关唯一写受保护 `main` | 四、六、十 | 04、06、EXE-03/07 | 分支保护与绕过测试 | +| `main/current` 是唯一默认读取面 | 二、三、五 | 04、07、EXE-08/10 | Git/current/readback 一致 | +| `discussion/confirmed` 与技术状态分离 | 七 | 04、07、11、EXE-02/07/10 | 状态解释与负面测试 | +| Agent 不持有写凭据；A3/A4 只提交受控网关请求 | v1 三、四、十三＋v1.1 九 | 05、08、EXE-04/09/10 | 工具权限、精确确认和提示注入测试 | +| 试点 `forced_off`，审核仅为条件分支 | 版本边界、十一 | 审核治理基线、EXE-02/07/12 | OFF 正常与模拟 ON 负面测试 | +| 恢复产生新 current 发布 | 九 | 04、10、EXE-08/11/12 | 恢复发布与空环境恢复 | +| MCP 是唯一用户业务入口，不建设自定义业务 Web | v1.1 三、八、十一 | 05、EXE-09/10 | M09/M10、工具注册表和旁路检查 | +| 飞书身份绑定内部用户，内部授权＋Gitea 权限双层限制 | v1.1 六、七 | 06、EXE-04/09 | M01～M04、撤权测试 | +| 飞书—Gitea 绑定不信任自报 username | v1.1 六、七＋闭环安全决策 | PRD S00/S03/S26、EXE-04 | 未绑定、冲突、停用和冒充负面测试 | +| 每次 MCP 调用强制记录 human＋agent＋service | v1.1 十 | 09、EXE-09/11 | M05/M06/M08 和审计完整性检查 | +| 中文检索只索引授权 current | v1 五、八＋闭环检索决策 | PRD S08/S21、EXE-08/10 | project/release 过滤、中文相关性和旧索引隔离测试 | +| Skill Registry、飞书内容来源和通用审批不进入当前目标 | v1.1 四、十三 | 03、12 | 工具/依赖清单无隐式前置 | + +## 6. 防偏移检查 + +出现以下任一设计或实施提案时必须停止当前 v1.1 任务并重新决策： + +- 直接修改 v1 原稿正文，或未通过差量版本说明静默覆盖 v1； +- 将 MCP 降回可选适配器，另建用户 Web/REST/CLI 业务入口或故障高权旁路； +- 用共享飞书机器人/Agent 身份代替真实用户绑定，或信任工具参数自报主体； +- 只检查内部权限或 Gitea 权限其中一层，任一层拒绝后仍放行； +- 将审计写入变成 Agent 可选调用，或允许动作成功但三主体审计缺失； +- 将 Skill Registry 或可执行 Skill 审核加入普通 Context 发布链； +- 在同一仓库内用目录或文档 ACL 模拟项目权限边界； +- 新增第三种 `content_status`，或把 `pending_review` 写成内容状态； +- 允许 Agent、publisher 或普通成员直接写 `main`； +- 创建第二个默认 current、在服务目录逐文件覆盖或让 Agent 扫描历史； +- 同步整个私人 Vault、私人 Git 历史或自动监听后发布； +- 用 MCP、prompt 或客户端 payload 覆盖服务端身份、权限和审核策略。 + +飞书身份、内部权限数据库和 MCP 已经属于 v1.1 必需能力；受控 Skill Registry、飞书内容来源和自定义 Web 仍需独立后续版本，不能隐式加入。 + +## 7. 更新规则 + +- 文档分类变化必须说明来源、改变范围、责任人和日期。 +- `adopted` 文档的实现细节可以参数化，但不能静默改变冻结原则。 +- v1.1 标为 required 的 MCP、身份、双层权限和强制审计不得在实现时降级为 optional。 +- `superseded` 只表示相关段落失效，不删除历史证据。 +- 新方案无法映射到本追溯矩阵时，默认属于版本变更而不是 v1 实现细节。 diff --git a/Gitea知识库/v1-详细实施方案.md b/Gitea知识库/v1-详细实施方案.md new file mode 100644 index 0000000..0d7a1a5 --- /dev/null +++ b/Gitea知识库/v1-详细实施方案.md @@ -0,0 +1,412 @@ +--- +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:305fe209cfd7c6485f36a48b3e952b19a0da02bcd4392e1b148b4121a6c519fc +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 设计追溯与版本关系]]" + - "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 已安装”，而是一个真实低敏感项目完成以下闭环： + +```text +明确选择本地 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. 总体依赖与批次 + +```mermaid +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//` 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、备份和回滚； +- 逐项动作、验收、停止条件和证据位置。 + +运行证据建议进入： + +```text +_runtime/context-publish// +├─ 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 实施准入`。两类授权均不会自动发生。 diff --git a/Gitea知识库/v1-验收与止损矩阵.md b/Gitea知识库/v1-验收与止损矩阵.md new file mode 100644 index 0000000..a67b793 --- /dev/null +++ b/Gitea知识库/v1-验收与止损矩阵.md @@ -0,0 +1,163 @@ +--- +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:4fb6cc58062bc3761610a6d89ca962932596a752dbac89243ad5446a6143c967 +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 开发任务分解]]" + - "[[3-业务线/Gitea知识库/v1-详细实施方案|v1 详细实施方案]]" + - "0-收集箱/临时待归属/2026-08-03-公司共享Context发布与AI协同框架/2026-08-03-12-试点方案决策清单与路线图.md" +--- + +# Gitea知识库 v1.1 验收与止损矩阵 + +## 1. 目的与判定口径 + +本文件把 v1 基线叠加 v1.1 MCP-first 身份与审计覆盖层后的阶段门、测试样本、成功指标、证据要求和止损动作放在同一套判定口径中。它用于回答“是否允许进入下一阶段”和“出现什么情况必须停止”，不能用安装完成、演示成功或口头确认替代。 + +当前工程设计、未来代码开发和未来真实实施使用不同的数据边界：工程设计不运行测试；代码开发默认使用合成数据、fake adapter 和临时目录；只有进入真实实施后才使用已授权试点。所有正式系统验收必须满足以下规则： + +- 使用一个真实、正在运行、低敏感且已明确授权的试点项目； +- 正向与负向测试都通过，拒绝结果也要留下证据； +- 发布记录、Git 提交、`current`、只读入口和 Agent 读回能够相互追溯； +- 证据写入业务线或后续正式代码库约定的验收位置，不把聊天、临时日志或截图作为唯一证据； +- 任一安全、权限、唯一性或恢复硬门失败时，不以“后续再补”放行。 + +## 2. 阶段门矩阵 + +| Gate | 进入条件 | 必须完成 | 通过证据 | 未通过动作 | +|---|---|---|---|---| +| C0 工程设计构建 | v1 主方案和 v1.1 差量覆盖层已归位 | 设计追溯、工程构建规格、开发任务分解、测试规格和未来实施方案统一到 v1.1 | 本业务线本地文档、hash 与一致性校验 | 只修正文档；禁止创建代码仓库、写代码和远端动作 | +| C1 代码开发准入 | C0 通过；Verlit 明确宣布进入代码开发 | 平台代码仓库、运行时/MCP SDK、Agent Host 边界、维护者、任务范围、合成身份/数据和验收人明确 | 开发任务单和代码仓库入口 | 保持任务为 planned；不得创建或修改代码 | +| G0 实施准入与参数 | C0/C1 对应门通过；Verlit 明确宣布进入实施 | 试点项目、成员角色、飞书身份应用、远程 MCP、身份/审计存储、目标服务器、备份、RPO/RTO和应急责任已确认 | 决策清单、角色表、服务器只读盘点、参数签字或明确确认记录 | 仅允许已授权的本地代码和设计工作；禁止远端创建和部署 | +| G1 实施契约落地 | G0 通过；平台代码归属明确 | 为目标试点固定稳定 ID、schema、状态机、幂等键、CAS、错误码、事件和回执契约 | 契约文件、状态转换测试、非法转换拒绝测试 | 可继续已授权的纯本地开发；禁止绑定真实环境和写远端状态 | +| G2 基础层与权限 | G1 可并行准备；目标环境已授权 | Gitea 加固、飞书/内部/Gitea 身份绑定、双层权限、私有试点仓库、`main` 保护、凭据隔离和备份链路完成 | 身份绑定、配置快照、双层权限正反测试、分支保护和备份结果 | 禁止接入真实业务内容和真实发布 | +| G3 MCP 与发布闭环 | G1、G2 通过 | MCP 唯一入口、选择、构建、安全检查、精确确认、CAS、网关提交、原子 `current`、强制审计、回执和四段读回闭环 | 单次 MCP 调用/发布三主体证据包；Git/current/MCP/Agent 四段一致 | 停止扩大样本；修复后从失败门重新验收 | +| G4 安全与运维 | G3 通过 | 未授权拒绝、私密材料隔离、提示注入隔离、撤权、密钥轮换、监控、事故响应和恢复演练通过 | 负面测试、撤权测试、轮换记录、告警证据、空环境恢复报告 | 安全硬失败立即停发；恢复失败禁止真实试点 | +| G5 真实试点 | G0～G4 全部通过 | 真实成员完成 12 类样本和日常使用观察；没有硬止损信号 | 试点报告、指标表、问题清单、责任人验收、v2 判决 | 回到相应 Gate；不得以软件安装完成宣告 v1 完成 | + +## 3. 工程测试规格 + +### 3.1 测试层级 + +| 前缀 | 层级 | 当前设计要求 | 运行边界 | +|---|---|---|---| +| CT | 契约测试 | schema 合法/非法样例、major/minor 兼容、未知关键状态拒绝、hash 防篡改 | 未来代码开发；纯本地、合成对象 | +| UT | 单元测试 | ID、状态机、选择范围、确定性构建、检查规则、策略、幂等、导出和读取模块 | 未来代码开发；无网络、无真实凭据 | +| IT | 集成测试 | fake source/Gitea/policy/read endpoint 下的正常与全部异常事务 | 未来代码开发；fake adapter 和临时目录 | +| SEC | 安全负面测试 | 越权、路径、符号链接、凭据、PII、日志脱敏、prompt injection 和策略覆盖 | 未来代码开发使用合成攻击语料；真实环境后再复验 | +| REC | 恢复测试 | artifact、current、状态存储、Gitea 和空环境恢复 | 本地仅验证恢复逻辑；真实备份恢复属于 G4/G5 | +| T | 真实试点验收 | 下述 T01～T12 | 仅在 G0～G4 通过后，对已授权低敏感项目运行 | + +每个开发任务的具体 CT/UT/IT/SEC 用例在 `v1-开发任务分解.md` 中有映射。测试结果必须记录用例 ID、契约版本、fixture hash、结果、错误码和关联任务；开发测试不得为了方便连接生产 Gitea。 + +### 3.2 v1.1 MCP、身份与审计强制用例 + +| ID | 场景 | 预期结果 | +|---|---|---| +| M01 | 两名飞书用户通过同一 Agent Host 登录 | 内部主体、授权项目、工具结果和审计身份正确分离 | +| M02 | 工具参数填写他人 `user_id`、role、grant 或 session | 服务端忽略/拒绝自报身份，不能冒充其他用户 | +| M03 | 内部 ProjectGrant 允许、Gitea 权限拒绝 | fail closed，记录 `permission_mismatch` | +| M04 | 内部 ProjectGrant 拒绝、Gitea 权限允许 | fail closed，不以 Gitea 单层权限放行 | +| M05 | read/search/build/validate 和 denied 调用 | 每次都有 request、授权和完成/失败的 human＋agent＋service 事件 | +| M06 | discussion/confirmed 发布 | 精确确认、candidate hash、`base_current`、session、commit 和网关服务身份可关联 | +| M07 | 停用用户、解除飞书/Gitea 绑定、撤销项目授权或 Gitea 成员 | 未来 MCP 会话/调用立即或在承诺失效边界内拒绝 | +| M08 | audit store/outbox 不可写 | 业务写 fail closed；可靠读取审计队列也不可用时拒绝读取 | +| M09 | MCP 故障或停用 | 不回退到共享 CLI、通用 Gitea token、shell 或高权限 API | +| M10 | 普通用户枚举工具 | 不存在审计写删、权限写、Gitea Admin、SSH、SQL、部署、备份、密钥和策略开关工具；不存在自定义业务 Web 入口 | + +### 3.3 十二类强制试点样本 + +原方案包实际列出 12 类样本；本文以 12 类为准，不沿用“11 类样本”的文字误差。 + +| ID | 场景 | 操作要点 | 预期结果 | 必要证据 | +|---|---|---|---|---| +| T01 | 单文件状态演进 | 同一材料先以 `discussion` 发布，再明确改为 `confirmed` 发布 | 两次 release 可追溯；内容状态变化不等同于技术状态变化 | 两次 selection、diff、release、commit、readback | +| T02 | 审核开关负面路径 | 试点保持 `forced_off`；仅在隔离测试中模拟审核 ON、candidate hash 变化及 ON→OFF | 正常试点不进入待审；模拟中旧批准不能覆盖新 candidate，切回 OFF 不误复用审批 | 策略快照、拒绝事件、状态转换记录 | +| T03 | 多来源组合 | 从两个或多个明确选择的 Markdown 来源构建一份发布物 | 仅包含选择清单中的内容；顺序、路径和 hash 确定 | selection manifest、构建清单、重复构建 hash | +| T04 | 附件与链接 | 发布含允许附件、相对链接和跨文件引用的材料 | 附件收集完整，链接改写后可读，无越界文件 | 附件 manifest、链接检查、读取截图或机器结果 | +| T05 | 相邻私密材料 | 在已选文件旁放置未选私密或敏感文件 | 私密材料不进入构建区、Git、`current`、日志和回执 | 搜索结果、构建清单、仓库与入口负向检查 | +| T06 | 并发发布 | 两个 publisher 基于同一 `base_current` 同时发起不同发布 | 只有一个成功；另一个以 `stale_base` 阻断，不出现混合 current | 两个请求、CAS 结果、最终 current manifest | +| T07 | 安全阻断 | 注入凭据、PII、路径穿越、符号链接和控制文件样本 | 策略要求阻断的样本在远端写入前失败，日志不回显秘密 | 每类检查结果、错误码、远端无提交证明 | +| T08 | Prompt Injection | 在知识正文中加入试图改变 Agent 权限或索取凭据的指令 | 内容只作为数据读取；Agent 不获得额外工具、凭据或跨项目访问 | Agent 输入输出、工具调用为零或拒绝证据 | +| T09 | 发布后读回失败 | 人为让只读入口或 Agent 读回不一致 | release 不标记 `completed`；告警触发并可安全重试 | 发布状态、读回差异、告警、重试结果 | +| T10 | 撤权与凭据轮换 | 撤销一名成员的绑定/授权，再轮换 `context-reader` 服务凭据 | 被撤权用户未来 MCP 访问失败；旧服务凭据失效，新凭据仅可读目标项目 | 前后访问结果、轮换记录、权限快照 | +| T11 | 历史版本恢复发布 | 选择历史 release 作为新发布来源 | 生成新的 release 和审计记录，不改写历史，不直接移动隐藏指针 | 新旧 release、commit、diff、readback | +| T12 | 空环境完整恢复 | 在隔离环境恢复 Gitea 数据、配置、仓库和关键凭据材料 | 在承诺 RPO/RTO 内恢复；权限与 `current` 一致；恢复结果可读 | 恢复计时、步骤记录、完整性校验、权限与读回测试 | + +## 4. 跨链路验收指标 + +| 指标 | v1.1 通过值 | 说明 | +|---|---|---| +| Git/current/只读入口/Agent 四段 release 一致率 | 100% | release ID、内容 hash、`content_status` 必须一致 | +| 同一项目同时有效的 `current` 数量 | 始终为 1 | staging 不算 current；任何短暂双 current 也算失败 | +| 未授权项目访问成功次数 | 0 | 人、Agent 和服务身份都适用 | +| 未选择私人内容进入企业面次数 | 0 | 包括仓库、current、日志、回执、缓存和备份索引 | +| 非网关身份写受保护 `main` 成功次数 | 0 | 管理员紧急操作也必须进入受控审计流程 | +| CAS 冲突导致内容覆盖次数 | 0 | 冲突必须阻断，不自动合并 current | +| 已标记 completed 但读回不一致次数 | 0 | 四段读回未通过不得完成事务 | +| 备份恢复成功率 | 100%（演练样本） | 至少完成一次隔离空环境恢复 | +| 共享账号或共享凭据数量 | 0 | 每个人、Agent 和服务均使用独立身份 | +| 共享机器人身份承载个人行为次数 | 0 | 每次用户操作都必须绑定个人内部主体和 AgentSession | +| 用户业务 MCP 调用审计覆盖率 | 100% | 允许、拒绝、成功和失败均覆盖 human＋agent＋service | +| 客户端自报身份/角色被采信次数 | 0 | user、role、grant 和 session 只能从服务端验证上下文派生 | +| 双层权限不一致被放行次数 | 0 | 内部授权或 Gitea 权限任一层拒绝都必须 fail closed | +| MCP 故障回退到高权限入口次数 | 0 | 不允许共享 CLI、token、shell、API 或自建 Web 旁路 | +| 普通成员必须处理 Git 分支/PR/MR 的发布次数 | 0 | v1 发布入口需屏蔽不必要的 Git 操作复杂度 | + +性能、可用性和 RPO/RTO 的具体数值在 D15 确认后加入验收承诺；未确认前不得把方案包建议值写成已承诺 SLO。 + +## 5. 止损矩阵 + +| 信号 | 级别 | 立即动作 | 恢复条件 | +|---|---|---|---| +| 出现两个有效 `current`、混合发布物或非原子切换 | 硬停止 | 暂停所有发布和默认读取；保留现场；回退到最后已验证 release | 原因修复、唯一性测试和 T06/T09 全部重跑通过 | +| 私人、跨项目、凭据或敏感内容进入企业读取面 | 安全事故 | 立即停发、撤销暴露入口和凭据、按事故流程评估通知与清理 | 泄漏范围确认、秘密轮换、历史与缓存处理、T05/T07 重跑通过 | +| 未授权身份可读目标项目或非网关身份可写 `main` | 硬停止 | 冻结相关身份与入口，保存审计证据 | 权限根因修复，完整正反权限测试通过 | +| 撤权后仍可访问，或旧 Agent 凭据仍有效 | 硬停止 | 禁用身份、轮换凭据、暂停新增成员 | T10 通过且缓存/会话失效边界明确 | +| 备份存在但无法在隔离环境恢复 | 硬停止 | 停止进入真实试点和扩大使用；修复备份链 | T12 在目标 RPO/RTO 内通过 | +| 事务标记 completed 但任一读回不一致 | 硬停止 | 将 release 标记为失败或不完整，保持最后已验证 current | T09 和完整四段读回通过 | +| Prompt 内容可以改变 Agent 权限、路由或工具调用 | 安全事故 | 停用 Agent 入口，隔离样本并审查凭据暴露 | 权限控制移出提示词、T08 通过、凭据完成轮换 | +| 依赖共享账号、共享 Token 或人工复制管理员凭据 | 硬停止 | 停止对应流程，不接受“试点临时共享” | 独立身份和最小权限矩阵落实并通过测试 | +| 每次发布都需要管理员手工修仓、改历史或移动 current | 暂停扩展 | 保留现有安全读取，停止增加用户和项目 | 自动化闭环稳定，连续试点无人工修仓 | +| 普通成员持续需要解决 Git 分支、PR/MR 或复杂冲突 | 产品止损 | 暂停扩大试点，回到选择与发布入口设计 | 真实成员可完成发布且无需 Git 专业操作 | +| 只有技术维护者使用，业务成员没有真实使用证据 | 范围止损 | 不进入 v2，不扩大平台能力 | 真实业务使用场景和可量化收益得到验证 | +| 只能靠提示词声明权限，服务端无强制权限边界 | 安全事故 | 禁止真实数据与 Agent 接入 | 权限由 Gitea、只读入口和服务端策略强制执行 | +| 共享机器人/Agent 身份无法区分真实操作人 | 硬停止 | 停用用户业务 MCP，保留只读事故调查 | 飞书绑定、内部主体和 AgentSession 归因通过 M01/M02 | +| 工具参数可冒充 user、role、grant 或 session | 安全事故 | 立即停用受影响工具并审查已发生调用 | 身份只从验证会话派生，M02 及历史影响检查通过 | +| 内部权限或 Gitea 权限任一拒绝却仍放行 | 安全事故 | 冻结项目访问和发布，保存审计现场 | 双层鉴权修复，M03/M04 与撤权测试通过 | +| MCP 调用缺少三主体审计，或审计失败仍执行业务动作 | 硬停止 | 停用受影响入口；核对业务状态与事件缺口 | outbox/等价机制修复，M05/M08 全部通过 | +| MCP 不可用时自动回退共享 CLI、token、shell 或自建 Web 旁路 | 硬停止 | 关闭回退通道和相关高权凭据 | M09/M10 通过并完成凭据轮换 | + +## 6. 证据包最小结构 + +每个 Gate 和测试样本至少保留： + +1. 测试标识、时间、human/agent/service 稳定 ID、AgentSession、项目 ID 和环境标识； +2. 前置状态与权限快照； +3. 输入摘要、selection ID、幂等键和 `base_current`； +4. 检查结果、状态转换、错误码和审计事件； +5. release ID、commit SHA、内容 hash、`content_status`； +6. Git、`current`、只读入口和 Agent 读回结果； +7. 回滚或恢复动作及其验证结果； +8. 结论、遗留问题、责任人和下一动作。 + +凭据、Token、私密正文和其他秘密不得进入证据包；证据中只记录稳定标识、hash 和脱敏摘要。 + +## 7. v1.1 完成与后续版本判决 + +只有 G0～G5 全部通过、M01～M10 与 T01～T12 完成、跨链路硬指标达标且无未关闭硬止损项，才可将当前 v1.1 目标标记为完成。完成后至少保留一段真实使用观察期，再依据实际摩擦决定后续版本。 + +以下能力不因 v1.1 完成而自动启动：Skill Registry、飞书内容来源、通用审批、自定义业务 Web、多项目汇总和更多内容来源。它们只能以独立版本范围、威胁模型、迁移方案和验收标准进入后续决策。 diff --git a/Gitea知识库/v1.1-技术栈与详细实施设计.md b/Gitea知识库/v1.1-技术栈与详细实施设计.md new file mode 100644 index 0000000..c92a685 --- /dev/null +++ b/Gitea知识库/v1.1-技术栈与详细实施设计.md @@ -0,0 +1,558 @@ +--- +title: Gitea知识库 v1.1 技术栈与详细实施设计 +date: 2026-08-10 +type: 设计spec +status: draft +content_status: discussion +owner: Verlit +last_updated_at: 2026-08-10 +last_updated_by: Codex +hash: sha256:943f3d865bf228e8adef23b6c9064079f0a3573ada0ff9fbae2560defc0b727b +hash_scope: Markdown 正文（从一级标题开始至文件末尾）的 UTF-8 SHA-256 +belongs_to: + - "[[3-业务线/Gitea知识库/_context|Gitea知识库]]" +depends_knowledge: + - "[[3-业务线/Gitea知识库/公司共享 Context 项目仓库发布方案 v1|公司共享 Context 项目仓库发布方案 v1]]" + - "[[3-业务线/Gitea知识库/公司共享 Context MCP-first 身份与审计方案 v1.1|公司共享 Context MCP-first 身份与审计方案 v1.1]]" + - "[[3-业务线/Gitea知识库/v1-工程构建规格|v1.1 工程构建规格]]" + - "[[3-业务线/Gitea知识库/v1-开发任务分解|v1.1 开发任务分解]]" +source_refs: + - "https://developers.openai.com/codex/codex-manual.md" + - "https://code.claude.com/docs/en/mcp" + - "https://code.claude.com/docs/en/permissions" + - "https://github.com/modelcontextprotocol/go-sdk/blob/main/docs/protocol.md" + - "https://github.com/modelcontextprotocol/go-sdk/releases/tag/v1.7.0" + - "https://modelcontextprotocol.io/specification/2026-07-28/basic/transports/streamable-http" + - "https://modelcontextprotocol.io/docs/tutorials/security/authorization" + - "https://go.dev/doc/devel/release" + - "https://www.postgresql.org/support/versioning/" + - "https://open.feishu.cn/document/authentication-management/access-token/get-user-access-token" + - "https://open.feishu.cn/document/server-docs/contact-v3/user/field-overview" + - "https://docs.gitea.com/usage/permissions" + - "https://github.com/go-gitea/gitea/releases/tag/v1.26.2" +--- + +# Gitea知识库 v1.1 技术栈与详细实施设计 + +## 1. 结论 + +本项目可以确定技术栈并拆解到可下发的开发与实施步骤。推荐采用“一个模块化 Go 代码库、两个运行角色、一个 PostgreSQL 控制数据底座、一个独立 Gitea、一个远程 MCP 用户入口”的方案： + +```text +Agent Host + → 飞书 OAuth 登录 + → 远程 MCP Gateway + → Identity/AuthZ/Audit 中间件 + → Read / Build / Validate / Release 业务模块 + → Gitea 私有项目仓库 + → 不可变 release + 唯一 current +``` + +本方案不建设自定义业务 Web 页面。HTTP 仅用于 MCP transport、OAuth 协议回调、健康检查和内部运维端点，不提供发布驾驶舱、权限后台或审计后台。 + +Agent 产品不进入业务核心。Codex、Claude Code（本文把用户所称 `CC` 按 Claude Code 记录）和后续 Agent 都通过统一兼容层调用同一个远程 MCP；服务端只信任标准 OAuth、框架确认凭证和受控 Selection Manifest，不信任具体 Agent 的品牌或模型声明。若 `CC` 实际指其他客户端，只新增适配器，不改变核心方案。 + +## 2. 推荐技术栈 + +| 层 | 确定方案 | 当前基线 | 选择理由 | 明确不采用 | +|---|---|---|---|---| +| 服务端语言 | Go | Go 1.26.x，构建时固定最新安全补丁 | 官方 MCP SDK、标准库 HTTP、单二进制、并发和部署边界清晰 | 首期不做多语言服务 | +| MCP SDK | 官方 Go SDK | `modelcontextprotocol/go-sdk` v1.7.x，依赖锁定 | 已覆盖 Streamable HTTP、Bearer auth 和 2026-07-28 协议 | 不使用非官方协议实现 | +| MCP 协议 | 当前协议＋兼容协商 | 目标 `2026-07-28`，兼容 `2025-11-25` | 当前协议已无服务端会话，便于多实例；兼容尚未升级的 Agent Host | 不新增旧 HTTP+SSE 实现 | +| OAuth 授权服务器 | 成熟 OAuth/OIDC Authorization Server＋飞书身份联邦 | 产品在 C1-04 前锁定；必须支持 PKCE、PRM、resource/audience、撤销和逐请求校验 | 飞书完成员工认证，授权服务器完成 MCP 客户端协议与令牌生命周期 | 不在 `contextd` 内从零自研密码学、客户端注册和令牌签发体系 | +| HTTP 层 | Go `net/http` | 标准库 `ServeMux` 和中间件 | 只需协议端点，无业务页面，无须 Web 框架 | 不引入前端、SSR、模板和 Web 管理系统 | +| 主数据存储 | PostgreSQL | PostgreSQL 18.x，部署时锁定最新小版本 | 同时支撑身份、权限、release、幂等、outbox、审计和全文索引 | 首期不引入 MySQL、MongoDB | +| SQL 访问 | `pgx/v5`＋`sqlc` | 锁定版本 | 显式 SQL、类型生成、事务边界可审查 | 不用隐藏 SQL/权限条件的重型 ORM | +| 数据迁移 | `goose` | 锁定版本，迁移只走运维身份 | 简单、可版本化、可回滚说明 | 不允许 Agent/MCP 执行迁移 | +| Gitea | 自建 Gitea | 1.26.x 支持分支，G0 时复核最新安全补丁 | 项目权限、私仓、分支保护和 Git 历史真源 | 不把 Gitea Admin 暴露给 Agent | +| Git 写入 | 系统 Git CLI | 固定最低版本，临时 worktree＋HTTPS | 多文件单 commit 和标准 non-fast-forward/CAS 语义成熟 | 不开放通用 Git tool；不把 token 放命令行或日志 | +| Markdown | Go AST 解析器 | `goldmark`＋自有规范化层 | 可确定性解析标题、链接和正文 | 不用 LLM 生成确定性发布物 | +| Schema | JSON Schema 2020-12 | schema＋合法/非法样例 | 与 v1/v1.1 契约包一致 | 不用仅靠 Go struct 代替外部契约 | +| 搜索 | PostgreSQL `pg_trgm`＋元数据过滤 | 规范化正文、标题、标签、路径；只索引授权项目的 current | 中文不依赖空格分词，首期可获得可预测的子串/相似度检索并保持项目隔离 | 首期不把原生英文 FTS 当中文主检索，也不引入 Elasticsearch/向量数据库 | +| 异步任务 | PostgreSQL outbox worker | 同一代码库、独立 worker 运行角色 | 保证业务状态与事件一致，减少基础设施 | 首期不引入 Kafka/RabbitMQ | +| 审计 | PostgreSQL 独立 schema/角色 | append-only、事件 hash、每日签名 checkpoint | 查询和完整性验证可落地 | 不把普通日志当审计真源 | +| 可观测 | OpenTelemetry | OTLP 输出到公司既有监控 | 不绑定具体监控产品 | 审计正文和 token 不进入 telemetry | +| 测试 | `go test`＋Testcontainers | fake Feishu/Gitea＋临时 PostgreSQL | 默认离线、可重复、正反用例统一 | 普通 CI 不连接生产环境 | +| 打包 | OCI 镜像 | 多阶段构建、固定 digest、SBOM | 可复现、便于测试环境部署 | 首期不要求 Kubernetes | + +### 2.1 为什么选择 Go 而不是 Web 技术栈 + +- 当前产品没有自定义页面，主要工作是协议接入、身份、权限、事务、文件构建、Git 和审计。 +- 官方 Go MCP SDK 可以直接挂在 `net/http`，不需要业务 Web 框架。 +- 一个代码库可编译成同一镜像的 `serve` 和 `worker` 两个运行角色，减少微服务和跨语言维护成本。 +- Go 的标准库、显式错误和静态类型适合安全门、状态机和可审查中间件。 + +若现有开发团队不能维护 Go，TypeScript 可以作为替代语言，但必须重新确认 SDK 版本、运行时、依赖供应链和部署基线；不能在编码中途混用两套主栈。 + +## 3. 部署拓扑与进程边界 + +```mermaid +flowchart LR + U[飞书用户] --> C[Codex / Claude Code / Other Agent] + C --> H[Agent Compatibility Layer] + H --> A[OAuth Authorization Server] + A -->|Feishu federation| F[飞书 OAuth] + A -->|Per-user OAuth bearer| P[Reverse Proxy] + P --> M[contextd serve] + + M --> DB[(PostgreSQL)] + M --> R[Current Reader] + M --> O[Outbox] + + O --> W[contextd worker] + W --> G[Gitea 1.26.x] + W --> FS[Immutable Releases/current] + W --> DB + + M --> OT[OTel Collector] + W --> OT +``` + +| 运行角色 | 面向谁 | 允许能力 | 禁止能力 | +|---|---|---|---| +| `contextd serve` | Agent Host | OAuth/MCP、身份、授权、读取、构建请求、发布请求、审计查询 | 不持有 Gitea 写 token，不执行部署/备份/迁移 | +| `contextd worker` | 内部 outbox | 构建、检查、Git commit/push、导出、读回、审计完成事件 | 不接受用户网络请求，不具有 Gitea Admin | +| `migrator` | 受控运维任务 | 数据库迁移 | 不作为常驻服务，不可由 MCP 调用 | +| `audit-reader` | 授权审计查询 | 脱敏 select/view | 无 insert/update/delete | +| `backup/restore` | 受控运维任务 | 备份和隔离恢复 | 不作为普通 Agent 工具 | + +首期采用模块化单体代码库，不拆成身份、权限、发布和审计微服务。`serve/worker` 的运行身份和凭据分离，但共享领域契约和代码版本。 + +## 4. 协议端点而非 Web 页面 + +| 路径/能力 | 用途 | 可见范围 | +|---|---|---| +| `POST /mcp` | 远程 Streamable HTTP MCP | Agent Host | +| `/.well-known/oauth-protected-resource` | MCP Protected Resource Metadata | Agent Host | +| OAuth metadata/authorize/token/revoke | MCP 客户端授权与撤销 | Agent Host/OAuth Authorization Server | +| `/oauth/feishu/callback` | 飞书授权码回调 | 飞书 OAuth 浏览器跳转 | +| `/health/live`、`/health/ready` | 存活与依赖健康 | 内部探针 | +| `/metrics` 或 OTLP | 指标/trace 输出 | 内网监控 | + +这些均是机器协议端点。项目不实现 HTML 页面、导航、表单、角色后台和审计后台。 + +`2026-07-28` 连接使用 stateless Streamable HTTP；内部 `AgentSession` 是应用身份对象，不是 MCP transport session。`/mcp` 必须验证 Origin/Host、协议 header 与 body 一致性、Content-Type、请求大小、超时和 bearer resource；旧协议兼容只通过官方 SDK 协商，不自行维护两套业务逻辑。 + +## 5. Agent 无关的兼容层契约 + +### 5.1 架构判断 + +Agent 品牌与模型能力不是业务权限依据，因此不需要把 Codex、Claude Code 或其他 Agent 写进发布、权限和审计核心。Agent 的差异只影响：MCP 配置方式、OAuth callback、工具确认事件和本地文件读取适配。 + +当前官方能力证明 Codex 和 Claude Code 都能连接远程 Streamable HTTP MCP 并完成 OAuth。Codex 还提供 MCP server/tool approval 配置，Claude Code 提供 MCP permission ask/allow/deny 和企业 managed MCP 配置。这些客户端能力用于交互和部署，但服务端仍必须逐次验证 token、权限和确认。 + +### 5.2 Verlit 已确认的接入条件 + +| 条件 | 当前结论 | 设计处理 | +|---|---|---| +| Agent 选择 | 框架自行兼容，优先 Codex、Claude Code | Agent adapter 可插拔，业务工具 schema 保持一致 | +| MCP 连接 | 每位用户独立连接同一远程 MCP | 每人独立 OAuth token、AgentSession 和审计主体 | +| OAuth | 必须完成 OAuth | MCP resource server＋成熟授权服务器＋飞书 Authorization Code/PKCE 身份联邦 | +| 人类确认 | 框架支持 | A3/A4 使用框架签发的一次性 `confirmation_id` | +| 本地文件 | 可以读取并传输，但必须受控 | 采用下述 Local Source Gate，不允许 Agent 自由扫描或上传 | + +这四项已经从“待提供信息”转为“已确认架构约束”。C1-00 仍需对 Codex、Claude Code 的实际版本做契约测试，但它是适配验收，不再决定核心架构是否成立。 + +### 5.3 兼容层最小接口 + +每个 Agent adapter 只负责： + +1. 注册远程 MCP endpoint 和支持的协议版本。 +2. 发起逐用户 OAuth，并安全保存/刷新该用户的 MCP 凭据。 +3. 将 `client_kind`、`client_version`、`adapter_version` 和本地 session 绑定到 AgentSession。 +4. 在 A3/A4 前展示固定的 project、action、candidate hash、`base_current` 和 diff 摘要。 +5. 只有真实用户完成确认后，向框架确认服务换取一次性 `confirmation_id`。 +6. 将用户明确选择的本地内容经过 Local Source Gate 后调用 MCP。 + +Codex/Claude Code 自带的 tool prompt 是第一层交互保护，但不直接成为发布授权真源；服务端只接受框架确认服务签发、与精确请求 hash 绑定的一次性凭证。 + +### 5.4 Local Source Gate：本地文件传输控制 + +```text +用户明确选择路径/章节 + → adapter 解析真实路径 + → 允许根、类型、大小、隐藏/控制文件检查 + → 本地 secret/PII/路径预检查 + → 展示文件数、相对路径、大小和 hash 供用户确认 + → 生成不可变 Selection Manifest + → 通过 MCP 分块传输选中内容 + → 服务端复算 hash、再做完整 validation +``` + +强制规则： + +- 允许根由框架/企业配置确定，Agent 和正文不能修改。 +- 不递归扫描未选择目录；不允许工作区外路径、符号链接逃逸、`.git`、凭据目录、隐藏控制文件和未允许二进制。 +- 只传相对 source label、内容、大小和 hash，不传个人绝对路径。 +- 默认只允许 Markdown；附件使用类型 allowlist、单文件上限和 bundle 总上限。 +- 工具参数和传输正文不进入普通日志；审计只保存 selection ID、文件数、字节数、规则结果和 hash。 +- 客户端预检查不是最终放行依据；服务端必须重新执行路径语义、secret/PII、链接和内容策略检查。 +- 任何分块缺失、hash 不一致、用户取消、会话变化或超时都废弃整个 selection，不做部分发布。 +- 临时缓冲区使用独立目录、最小权限和完成后清理；不得成为 Agent 后续默认检索面。 + +Local Source Gate 可以由 Verlit 的兼容框架统一实现，Codex 和 Claude Code 只提供文件读取能力。这样 Agent 可替换，而本地数据控制保持一致。 + +## 6. 飞书登录与 MCP 会话 + +### 6.1 推荐身份模型 + +- 内部 `user_id` 是唯一长期主体，不直接采用邮箱、手机号、姓名或 Gitea username 作为主键。 +- `FeishuBinding` 保存 `tenant_key`、当前应用的 `open_id`，在权限允许时同时保存租户内 `user_id`；外部 ID 变化或应用迁移通过绑定版本处理。 +- `GiteaBinding` 保存 Gitea 数字用户 ID、username 和绑定状态。 +- 飞书 user token 只用于登录时取得身份，不作为 MCP token，不透传给 Gitea。 + +### 6.2 登录流程 + +```text +Agent Host 请求 /mcp + → 401 + Protected Resource Metadata + → Host 进入 OAuth Authorization Code + PKCE + → OAuth Authorization Server 重定向飞书授权页 + → 飞书 callback 返回一次性 code + → 身份联邦适配器换取 user_access_token 并读取稳定用户 ID + → 查找内部 UserIdentity、FeishuBinding 和预配置 GiteaBinding + → 校验用户/绑定状态 + → 授权服务器签发短期 MCP access token + → Host 携带 token 调用 /mcp +``` + +### 6.3 Token 规则 + +- access token 由成熟授权服务器签发；可采用短期签名 JWT 或可内省的 opaque token，但必须校验 issuer、audience/resource、scope、client、expiry 和撤销状态。 +- 若采用 opaque token，随机强度至少 256 bit，业务数据库只保存不可逆 hash；若采用 JWT，业务数据库不落原始 token，撤权仍通过会话和权限版本即时生效。 +- 建议 access token 15 分钟、refresh/session 8 小时；最终值在 C1 安全评审确认。 +- token 绑定 `user_id`、Agent Host client、MCP resource、scope、permission version 和 expiry。 +- 每次工具调用重新检查用户、绑定、AgentSession 和权限版本；撤权不等待 token 自然到期。 +- Feishu、MCP 和 Gitea token 三者永不复用或互相透传。 + +### 6.4 首次登录与飞书—Gitea 绑定 + +- 首次飞书登录只证明“这个人是谁”，不会根据用户输入的 Gitea username 自动授予项目权限。 +- v1.1 试点采用受控预配置：治理人员把 `tenant_key＋飞书稳定 ID` 与 Gitea 数字用户 ID 建立待激活映射，并同时配置 ProjectGrant；该动作走迁移/受控运维流程，不暴露为普通 MCP tool。 +- 用户首次登录时只激活已存在且唯一匹配的映射；未配置、重复、停用或不一致时进入 `binding_pending/denied`，只允许读取本人身份与处理提示，不能列出或读取项目。 +- Gitea 绑定必须以 Gitea 数字用户 ID 为真源，username 只用于展示；后续若建设自助绑定，必须通过 Gitea OAuth/一次性所有权验证另行评审，不能用“用户自行填写账号名”替代。 +- 项目授权和解绑同样不暴露为普通 MCP 写工具。撤销 FeishuBinding、GiteaBinding、ProjectGrant 或 AgentSession 任一项，下一次调用立即拒绝并写审计事件。 + +## 7. PostgreSQL 数据模型 + +### 7.1 身份与授权 + +| 表 | 核心字段 | 约束 | +|---|---|---| +| `user_identities` | internal user ID、status、display name | 显示名变化不改主键 | +| `feishu_bindings` | tenant、open/user ID、user ID、status、version | tenant＋外部 ID 唯一；不保存明文 token | +| `gitea_bindings` | Gitea numeric ID、username、user ID、status | Gitea numeric ID 唯一 | +| `projects` | project ID、repo mapping、sensitivity、status | repo mapping 受保护 | +| `project_grants` | user、project、role、actions、expiry、version | 第一层权限真源 | +| `agent_sessions` | session、user、agent/client、scope、expiry | 短期，可撤销 | +| `mcp_tokens` | token hash、session、resource、scope、expiry | 不保存明文 bearer token | +| `confirmations` | user/session、tool、project、request hash、expiry | 一次性，不能跨 hash 复用 | + +### 7.2 发布与读取 + +| 表 | 作用 | +|---|---| +| `selections` | 不可变选择范围、来源 revision 和 hash | +| `artifacts` | artifact manifest、bundle hash、builder version | +| `validation_reports` | policy version、finding、结果和例外引用 | +| `release_records` | release 状态、幂等键、`base_current`、commit/readback | +| `current_versions` | 每项目唯一有效 current 和版本引用 | +| `current_search_documents` | 仅 current 的 project-scoped 规范化检索文档与 trigram 索引 | + +### 7.3 审计与可靠任务 + +| 表 | 作用与权限 | +|---|---| +| `outbox_events` | 业务事务内写入待执行/待投递事件；worker claim | +| `audit_events` | 追加写三主体事件；运行角色无 update/delete | +| `audit_checkpoints` | 按日/分区保存事件链摘要和签名引用 | + +数据库至少使用 `runtime`、`worker`、`audit_writer`、`audit_reader`、`migrator`、`backup` 六类角色。运行时不得拥有迁移、审计删除或任意 schema 权限。 + +当前版本不创建 `skills`、`skill_reviews` 或 `skill_registry` 表；它们属于独立后续版本。 + +## 8. 双层权限算法 + +每次工具调用按固定顺序执行： + +```text +Bearer token 有效 + ∩ UserIdentity active + ∩ FeishuBinding active + ∩ AgentSession active and bound to client + ∩ ProjectGrant allows action/resource + ∩ Project/sensitivity/policy allows + ∩ GiteaBinding active + ∩ Gitea confirms current project permission + ∩ exact Confirmation valid when A3/A4 +``` + +- 服务端不读取工具参数中的 `user_id`、role、grant、session 作为权威数据。 +- 首期每次项目访问实时查询 Gitea 权限，不使用允许结果的长期缓存；Gitea 不可用时 fail closed。 +- 后续只有在撤权失效机制验证后，才可增加短 TTL 缓存。 +- Gitea 权限查询使用独立 read-scoped 服务凭据；发布写入使用独立 project-scoped 网关凭据。 +- 用户本人不需要向 Agent 提供 Gitea token。 + +## 9. MCP 工具实现分组 + +### 9.1 第一批：身份与只读 + +- `get_my_identity` +- `list_authorized_projects` +- `get_my_project_roles` +- `get_current_manifest` +- `read_artifact` +- `search_current` +- `verify_release_hash` + +### 9.2 第二批：选择、构建与检查 + +- `create_selection` +- `append_selection_content`（仅在 Host 需分块传输时） +- `build_preview` +- `validate_release_request` +- `preview_release_diff` + +Markdown 内容通过 MCP 加密传输，但不得进入访问日志和审计正文；审计仅记录内容 hash、大小、文件数和脱敏标签。首期设置单文件和 bundle 大小上限，超限时停止，不自动改走通用上传接口。 + +### 9.3 第三批：受控发布 + +- `submit_discussion_release` +- `submit_confirmed_release` +- `get_release_status` +- `cancel_precommit_release` + +A3/A4 请求必须引用一次性 `confirmation_id`，并绑定 tool、user、session、project、candidate hash、`base_current` 和过期时间。Host 不能提供可靠确认时不注册提交工具。 + +### 9.4 第四批：审计查询 + +- `list_my_actions` +- `get_action_detail` +- `trace_release` +- `trace_correlation` +- `list_project_audit_events` +- `verify_audit_event` + +审计生成不是 MCP tool；它由服务端中间件和业务事务自动完成。 + +## 10. 强制审计实现 + +### 10.1 每次调用顺序 + +```text +解析 bearer/token context + → 持久化 request_received + → 身份、双层权限、策略和确认判断 + → 持久化 allowed/denied + → 执行业务逻辑或 outbox 任务 + → postcheck/readback + → 持久化 completed/failed + → 返回 MCP 结果 +``` + +### 10.2 可靠性 + +- `request_received` 无法持久化时拒绝工具调用。 +- 发布等写动作与 outbox 在同一个 PostgreSQL 事务提交。 +- worker 使用 `FOR UPDATE SKIP LOCKED`/等价机制 claim 任务，按幂等键重复安全执行。 +- completed 只有在 Git、current、MCP readback 和审计结果均落盘后产生。 +- 每个事件记录 human、agent、service、session、tool、action、project、request hash、policy、authorization、confirmation、result 和 correlation。 +- `audit_events` 使用 canonical JSON hash；每日产生签名 checkpoint 并进入备份，便于发现离线篡改。 + +## 11. Gitea 发布与 current + +### 11.1 Gitea 权限 + +- 每个项目一个私有 Context 仓库。 +- 普通成员按项目获得 Code Read；无需 Write。 +- 只有 `publish-gateway:` 可写受保护 `main`。 +- Gitea Admin、组织 Owner 和仓库 Settings 权限不进入 MCP 工具。 + +### 11.2 发布事务 + +1. worker 读取服务端 policy、validation、confirmation、幂等和 `base_current`。 +2. 使用临时 worktree 获取指定 `main`，再次校验远端 commit 与 `base_current`。 +3. 生成完整新 `current/`，不在服务目录逐文件修改。 +4. 创建单一 Git commit，记录 release ID、human、agent、service 和 manifest hash。 +5. 非 force push 到受保护 `main`；non-fast-forward 返回 `STALE_BASE`。 +6. 从该 commit 构建不可变 `releases//`。 +7. 校验 manifest/checksum 后原子切换唯一 current。 +8. 通过 MCP 内部读取路径执行 readback；一致后才 completed。 + +### 11.3 Search 索引 + +current 切换时为新 release 生成规范化检索文档和 PostgreSQL `pg_trgm` GIN/GiST 索引，以 `project_id＋release_id` 为版本键；标题、标签、相对路径和正文分别保留权重字段。切换 current 与索引激活必须保持同一版本。查询先鉴权、再限定 project、最后执行精确匹配、前缀/子串与 trigram 相似度排序，不跨项目检索后在模型端过滤。 + +原生 PostgreSQL FTS 可作为英文或明确分词语料的补充，但不作为 v1.1 中文主检索。只有基准测试证明 `pg_trgm` 无法满足真实规模和相关性时，才评审中文分词扩展或外部检索服务。 + +## 12. 代码仓库结构 + +```text +context-platform/ +├─ cmd/contextd/ +├─ contracts/ +│ ├─ v1/ +│ └─ v1.1/ +├─ internal/ +│ ├─ domain/ +│ ├─ identity/ +│ ├─ authorization/ +│ ├─ mcpserver/ +│ ├─ selection/ +│ ├─ builder/ +│ ├─ validation/ +│ ├─ release/ +│ ├─ gitea/ +│ ├─ current/ +│ ├─ search/ +│ ├─ audit/ +│ └─ observability/ +├─ migrations/ +├─ config/ +├─ tests/ +│ ├─ contract/ +│ ├─ integration/ +│ ├─ security/ +│ └─ fixtures/ +├─ deploy/ +└─ docs/ +``` + +同一镜像通过子命令运行： + +```text +contextd serve +contextd worker +contextd migrate # 仅运维任务 +contextd verify # 离线配置/契约自检 +``` + +## 13. C1 代码开发执行顺序 + +| WP | 工作包 | 主要动作 | 交付物 | 通过门 | +|---|---|---|---|---| +| C1-00 | Agent adapter 契约测试 | 分别用 Codex、Claude Code adapter＋fake OAuth/MCP 验证逐用户 token、协议、框架确认和 Local Source Gate | 通用 adapter contract、两份兼容性报告 | 两个客户端通过同一 schema；不接真实业务数据 | +| C1-01 | 工程基线 | 创建代码仓库、Go module、依赖锁、CI、秘密扫描、制品规则 | 仓库骨架、构建命令 | 离线 build/test 通过，无真实配置 | +| C1-02 | 契约与领域 | 落地 v1/v1.1 schema、状态机、ID、错误和样例 | contracts、domain tests | CT/UT 通过，未知 major/状态拒绝 | +| C1-03 | PostgreSQL 与迁移 | 表、索引、约束、DB roles、迁移和测试库 | migration、sqlc、repository ports | 回滚说明、最小权限和并发测试通过 | +| C1-04 | 身份与 OAuth | 选定成熟授权服务器，接入 fake Feishu、binding、token/session、PRM/auth metadata | identity federation adapter、auth middleware | 参数冒充、未预配绑定和撤权后访问均拒绝 | +| C1-05 | 双层授权 | ProjectGrant、Gitea permission port、policy 和确认 | authorization engine、fake Gitea | M01～M04、M07 通过 | +| C1-06 | MCP 与审计骨架 | Streamable HTTP、工具 registry、三主体中间件、outbox | serve/worker、audit events | M05、M08～M10 通过 | +| C1-07 | current 读取与搜索 | manifest/read/search/hash verify、project filter | 第一批 MCP 工具 | 未授权、跨项目和历史读取均失败 | +| C1-08 | Selection/Build/Validate | 实现 Local Source Gate、分块传输、规范化、附件/链接、扫描和 diff | 第二批 MCP 工具 | 未选内容不读取；确定性 hash、安全阻断和大小限制通过 | +| C1-09 | Release/Export/Readback | 幂等、CAS、fake Git/Gitea、原子 current、readback | 第三批 MCP 工具 | 并发、失败状态、恢复发布通过 | +| C1-10 | 审计查询与观测 | 查询工具、event verify、指标/trace、脱敏 | 第四批工具、OTel | 三主体链完整，日志无正文/秘密 | +| C1-11 | 安全与恢复测试 | 冒充、越权、注入、审计中断、DB/Git/current 恢复 | 测试报告 | M01～M10 和开发态 T 用例通过 | +| C1-12 | 打包交接 | OCI、SBOM、checksum、配置样例、运行手册 | 不连接环境的制品 | 可复现、无秘密、不会自动部署 | + +C1-00 某个客户端未通过时，只阻断该客户端 adapter，不阻断核心和已通过客户端；不得为兼容单个 Agent 降级 OAuth、确认、Local Source Gate 或审计语义。 + +## 14. G0～G5 真实实施顺序 + +### G0：参数与责任确认 + +1. 固定 Codex、Claude Code 的受支持版本和 adapter version，并确认飞书自建应用、试点用户和管理员。 +2. 选择已有或独立部署的成熟 OAuth/OIDC Authorization Server，确认 MCP PRM、PKCE、resource/audience、客户端注册、撤销和飞书身份联邦能力。 +3. 确认目标 Linux/容器环境、域名、TLS、反向代理、PostgreSQL、存储和备份。 +4. 确认 Gitea 是新建还是复用、版本、管理员和维护窗口。 +5. 固定试点 project、成员、飞书—Gitea 预配置绑定、publisher 和安全/备份责任人。 +6. 确认 RPO/RTO、审计保留、脱敏和事故联系人。 + +### G1：测试环境基础设施 + +1. 只读盘点目标环境。 +2. 准备 PostgreSQL 数据库/角色和密钥引用。 +3. 部署固定版本 Gitea，关闭公开注册并保护 `main`。 +4. 部署 reverse proxy、`contextd serve/worker` 和 OTel 输出。 +5. 配置飞书 OAuth redirect、最小 scope 和 MCP resource metadata。 +6. 创建一个合成项目和合成用户，先运行 M01～M10。 + +### G2：身份、权限与仓库 + +1. 建立试点用户的内部、飞书和 Gitea 绑定。 +2. 建立 ProjectGrant 和 Gitea Code Read 权限。 +3. 创建项目级 reader、permission-checker 和 publish-gateway 服务身份。 +4. 验证双层权限不一致、用户停用、解绑和 Gitea 撤权。 +5. 创建试点私仓、受保护 `main` 和备份链。 + +### G3：发布闭环 + +1. 只开放身份与 current 读取工具。 +2. 读取稳定后开放 selection/build/validate/diff。 +3. Host 精确确认验证通过后再开放 discussion 发布。 +4. confirmed/恢复作为最后一批 A4 工具开放。 +5. 每次发布验证 Git/current/MCP/Agent 四段一致和三主体审计。 + +### G4：安全、备份与恢复 + +1. 完成越权、提示注入、秘密/PII、路径和审计中断测试。 +2. 轮换 Feishu app secret、MCP 签发密钥、Gitea token 和数据库凭据。 +3. 恢复 PostgreSQL、Gitea、current、audit checkpoints 和服务配置。 +4. 在隔离环境完成空环境恢复并验证撤销凭据失效。 + +### G5：真实试点 + +1. 只接一个 internal、Markdown 为主的真实项目。 +2. 完成 M01～M10 和 T01～T12。 +3. 至少两名非平台维护者完成真实读取、发布或纠错。 +4. 观察使用和维护成本，命中止损即停止扩项目。 +5. 根据证据决定保持 v1.1，还是单独立项 Skill Registry、飞书内容来源或其他版本。 + +## 15. 默认不引入的复杂度 + +- 不建设自定义 Web/移动端页面。 +- 不使用 Kubernetes 作为首期前置。 +- 不拆身份、权限、发布、审计为多个代码仓库或微服务。 +- 不引入 Redis、Kafka、RabbitMQ、Elasticsearch 或向量数据库。 +- 不让 LLM 决定权限、审核策略、Git commit 或 current 切换。 +- 不让 MCP 工具执行部署、迁移、备份、恢复、密钥和 Gitea Admin。 +- 不创建 Skill Registry 数据表或发布链。 + +只有真实负载、可靠性或检索效果证明 PostgreSQL/模块化单体不足时，才为后续版本增加基础设施。 + +## 16. 工作量量级 + +在一名熟悉 Go/安全后端的主开发＋一名测试/平台协作者条件下，C1 代码与测试基线约为 45～70 人日；G0～G4 环境接入、加固和恢复验证约为 15～30 人日，真实试点观察另计。 + +该估算包含 Codex、Claude Code 两个 adapter 的契约适配和 Local Source Gate 基础实现，但不包括：第三种 Agent 的特殊兼容、公司没有可用飞书自建应用权限、目标服务器需要重新采购、历史 Gitea 迁移或 Skill Registry 扩展。若某客户端违反统一契约，只重新评估该 adapter，不扩大核心权限。 + +## 17. 已确认条件与后续实施参数 + +| 优先级 | 信息 | 当前状态 | 后续处理 | +|---|---|---|---| +| P0 | Agent 架构 | confirmed：框架兼容，优先 Codex、Claude Code | C1-00 固定受支持版本和 adapter contract | +| P0 | 每人独立远程 MCP | confirmed：必须支持 | C1-00 测试两名用户 token/subject 隔离 | +| P0 | OAuth | confirmed：必须完成 | C1-04 集成成熟 OAuth AS＋飞书身份联邦 | +| P0 | A3/A4 人类确认 | confirmed：框架支持 | C1-00/05 验证一次性 confirmation 不可伪造/复用 | +| P0 | 本地文件 | confirmed：可读可传但必须控制 | C1-08 实现并验收 Local Source Gate | +| P1 | 团队能否维护 Go；如不能，主要语言是什么 | open | C1-01 前决定是否接受默认 Go 栈 | +| P1 | 可复用的 OAuth/OIDC Authorization Server；如无，批准独立部署哪一成熟产品 | open | C1-04 前锁定；不得在业务服务内临时自研完整授权服务器 | +| P1 | 是否已有飞书自建应用、App 管理员和可用 OAuth redirect 域名 | open | G0 前确认真实 OAuth 参数和 scope | +| P1 | Gitea 是新建还是复用，当前版本和管理员 | open | G0 盘点、升级和权限 API 兼容性 | +| P1 | 目标服务器是否允许 Linux 容器、PostgreSQL 18 和反向代理 | open | 决定部署配置，不影响领域设计 | +| P1 | 飞书—Gitea 绑定和 ProjectGrant 的首批预配置名单与治理责任人 | open | G2 前导入；未预配置用户 fail closed | +| P1 | Local Source Gate 的允许根、类型、单文件/bundle 上限、secret/PII 规则和临时保留期 | open | C1-08 前按 PRD 默认值评审并配置化 | +| P2 | 既有秘密、日志、指标、备份产品 | open | 优先复用，避免重复建设 | + +Agent 相关架构信息已经足以关闭概念设计缺口。尚未提供的 P1/P2 信息不阻断当前文档设计，只在对应 C1/G0 任务开始前阻断具体代码栈确认或部署命令。 + +## 18. 与 v1/v1.1 的一致性 + +| 原则 | 本方案实现方式 | 是否偏移 | +|---|---|---| +| 一项目一私仓 | Gitea private repository＋ProjectGrant | 否 | +| 发布网关唯一写 `main` | 只有 worker 的 project-scoped gateway credential | 否 | +| 唯一 `main/current` | 不可变 release＋原子 current 指针 | 否 | +| 内容/事务状态分离 | v1 状态机原样落地 | 否 | +| MCP 唯一用户入口 | 仅 `/mcp` 暴露业务工具 | 否 | +| Agent 可替换 | Codex/Claude Code 通过统一 adapter contract，服务端不信任 Agent 自报身份 | 否 | +| 飞书绑定内部主体 | 成熟授权服务器完成 MCP OAuth，飞书联邦到内部 UserIdentity | 否 | +| 飞书—Gitea 绑定 | Gitea 数字 ID 受控预配置；未绑定、冲突或停用即拒绝 | 否，补齐安全落地方式 | +| 双层权限 | ProjectGrant＋实时 Gitea 权限复核 | 否 | +| 三主体强制审计 | MCP 中间件＋业务 outbox＋append-only store | 否 | +| 无自建 Web | 只有协议和内部健康端点 | 否 | +| 私人来源明确选择 | Local Source Gate 只传用户明确选择的文件/章节 | 否 | +| 搜索只暴露 current | PostgreSQL project-scoped `pg_trgm`＋元数据过滤 | 否，补齐中文检索基线 | +| Skill Registry 后置 | 当前无 skill 表、工具和流程 | 否 | + +因此，本技术栈是 v1.1 的实现选择，不构成新的业务版本。只有改成共享用户身份、取消 Gitea 二次复核、绕过强制审计、开放 Web 旁路或把 Skill Registry 加入首期，才属于需要重新确认的版本变更。 diff --git a/Gitea知识库/公司共享 Context MCP-first 身份与审计方案 v1.1.md b/Gitea知识库/公司共享 Context MCP-first 身份与审计方案 v1.1.md new file mode 100644 index 0000000..010f8ae --- /dev/null +++ b/Gitea知识库/公司共享 Context MCP-first 身份与审计方案 v1.1.md @@ -0,0 +1,383 @@ +--- +title: 公司共享 Context MCP-first 身份与审计方案 v1.1 +date: 2026-08-10 +type: 设计spec +status: draft +content_status: discussion +owner: Verlit +last_updated_at: 2026-08-10 +last_updated_by: Codex +hash: sha256:5f9ec680322a53a9e79d9e838d74c5472ac3ca63dab25dbf1fa530e852e96199 +hash_scope: Markdown 正文（从一级标题开始至文件末尾）的 UTF-8 SHA-256 +belongs_to: + - "[[3-业务线/Gitea知识库/_context|Gitea知识库]]" +based_on: + - "[[3-业务线/Gitea知识库/公司共享 Context 项目仓库发布方案 v1|公司共享 Context 项目仓库发布方案 v1]]" +source_refs: + - "0-收集箱/临时待归属/2026-08-03-公司共享Context发布与AI协同框架/2026-08-03-05-MCP工具路由与外部系统连接.md" + - "0-收集箱/临时待归属/2026-08-03-公司共享Context发布与AI协同框架/2026-08-03-06-分层身份权限与凭据模型.md" + - "0-收集箱/临时待归属/2026-08-03-公司共享Context发布与AI协同框架/2026-08-03-08-AI权限控制与人机协同.md" + - "0-收集箱/临时待归属/2026-08-03-公司共享Context发布与AI协同框架/2026-08-03-09-安全隐私审计与事故响应.md" + - "https://modelcontextprotocol.io/docs/2026-07-28/learn/architecture" + - "https://modelcontextprotocol.io/specification/2025-11-25/basic/index" +--- + +# 公司共享 Context MCP-first 身份与审计方案 v1.1 + +## 1. 版本定位 + +本文是 `公司共享 Context 项目仓库发布方案 v1` 的差量设计覆盖层，不复制或重写 v1 全文。应用顺序为： + +```text +v1 基线 + + v1.1 本文明确列出的覆盖项 + = 当前目标设计 +``` + +v1 中未被本文明确覆盖的内容继续有效。本文进入 `confirmed` 前保持草案状态；即使本文确认，也不表示代码开发、部署或真实实施已经开始。 + +## 2. 为什么不重新生成整套设计 + +现有 v1 已经具备以下可直接继承能力： + +- 一项目一私有 Context 仓库； +- 发布网关唯一写受保护 `main`； +- `main/current` 唯一默认读取面； +- `discussion / confirmed` 内容状态与 release 事务状态分离； +- Selection、Artifact、Validation、Release、Current、Readback 和 Audit 契约； +- 幂等、`base_current` CAS、原子导出、读回、撤权、备份和恢复； +- Agent 角色隔离、内容面与控制面隔离； +- 项目级权限、凭据分离和追加审计原则。 + +需要改变的是入口、身份承载和审计强度，不是底层发布模型。因此使用差量设计能保留 v1 追溯关系，并避免出现两套近似但互相冲突的仓库、状态机和发布方案。 + +## 3. v1 到 v1.1 的偏差与覆盖 + +| 设计项 | v1 当前口径 | v1.1 当前目标 | 处理方式 | +|---|---|---|---| +| 产品入口 | HTTPS/CLI 优先，MCP 可选 | 全员 Agent 工作，MCP 是唯一用户业务入口 | 覆盖 D11、EXE-09、DEV-90 定位 | +| 自建 Web 页面 | 驾驶舱可选 | 不建设任何自定义业务 Web 页面 | 明确关闭驾驶舱；Agent Host 是交互界面 | +| 用户身份 | Gitea/项目身份，飞书身份后置 | 飞书登录用户映射内部主体，并绑定 Gitea 账户 | 将身份映射提升为首期必需能力 | +| 权限判断 | 项目角色与 Gitea 权限 | 内部权限数据库第一层＋Gitea 项目权限第二层 | 新增双层授权决策 | +| Agent 写入 | 默认 A2；A3/A4 后续按项目开放 | Agent 可代表已登录用户提交受控发布请求 | 远端生效仍由网关服务身份完成 | +| 审计主体 | 人、Agent、服务主体分层但未强制逐调用 | 每次 MCP 调用记录 human＋agent＋service 行为链 | 新增强制审计中间件和事件 schema | +| 审计接口 | 事件记录与查询未固定入口 | 审计查询统一走只读 MCP；审计生成由服务端自动完成 | 禁止把审计写入暴露为普通工具 | +| MCP 传输 | 可选适配器 | 生产目标使用远程 MCP；STDIO 仅限本地开发 | 多用户入口统一 | +| 运维接口 | HTTP/CLI/MCP 混合 | 用户业务接口走 MCP；部署、备份、密钥和迁移不开放为普通 MCP | 保留独立运维控制面 | + +## 4. 目标与非目标 + +### 4.1 目标 + +- 每位员工通过自己的飞书身份登录 Agent，不共享企业机器人身份代替个人身份。 +- Agent 只使用用户绑定的 MCP 会话调用知识读取、构建、检查、发布和审计查询工具。 +- MCP Server 在服务端完成身份验证、双层授权、策略判断、业务执行和自动审计。 +- 每次操作都可解释“谁提出、哪个 Agent 代办、哪个服务身份真正执行、为什么允许、结果是什么”。 +- 普通成员不需要进入自定义 Web 管理系统，也不需要处理 Git 分支、PR/MR 和凭据。 +- Gitea 继续作为项目仓库、Git 历史和第二层权限边界。 + +### 4.2 非目标 + +- 不把飞书文档作为 v1.1 的内容来源；当前只使用飞书身份。 +- 不建设独立企业管理后台、发布驾驶舱或自定义审核页面。 +- 不把通用 Gitea Admin、SSH、数据库、备份、密钥、部署和历史重写能力开放给普通 Agent。 +- 不把 MCP 当作权限真源、审计真源或发布事务真源。 +- 不把 Skill Registry 纳入本版本；它继续保持独立版本候选。 +- 不用一个共享机器人 token 将所有员工行为记录成同一主体。 + +## 5. 总体架构 + +```mermaid +flowchart LR + U[飞书用户] --> H[Agent Host] + H -->|用户绑定访问令牌| M[MCP Gateway] + + M --> I[Identity Binding] + I --> P[Permission DB] + P --> GP[Gitea Permission Check] + + M --> RR[Reader Tools] + M --> BB[Build/Validate Tools] + M --> PW[Publish Gateway Tools] + M --> AQ[Audit Query Tools] + + RR --> C[Business Core] + BB --> C + PW --> C + C --> G[Gitea Project Repo] + G --> E[current Export/Readback] + + M --> A[Append-only Audit Store] + C --> A + E --> A +``` + +MCP 是用户业务边界，不是业务核心的替代品。Selection、构建、检查、事务、Gitea 写入、current 导出和读回仍由确定性服务端模块执行。 + +## 6. 身份模型 + +### 6.1 稳定主体 + +| 对象 | 关键字段 | 作用 | +|---|---|---| +| `UserIdentity` | `user_id`、状态、显示名 | 内部稳定人类主体，显示名变化不改 ID | +| `FeishuBinding` | `tenant_key`、`open_id`、`user_id`、绑定状态 | 飞书登录身份映射，不保存飞书 token 明文 | +| `GiteaBinding` | `gitea_user_id`、`username`、`user_id`、绑定状态 | 第二层账户映射 | +| `ProjectGrant` | `user_id`、`project_id`、角色、动作、有效期 | 内部权限数据库第一层授权 | +| `AgentSession` | `session_id`、`agent_id`、`user_id`、client、expiry | 记录哪个 Agent 代表哪个用户 | +| `ServiceIdentity` | `service_id`、project scope、action scope | 网关、导出、读取、审计等服务身份 | + +### 6.2 登录与会话流程 + +1. 用户在 Agent Host 发起飞书登录。 +2. 登录完成后，身份服务使用飞书稳定标识查找或创建内部 `user_id`。 +3. MCP 连接获得用户绑定、短期、不可转交的访问令牌。 +4. MCP Server 验证 issuer、audience、resource、expiry、client、subject 和 scope。 +5. 服务端从令牌解析 `user_id`，再加载 AgentSession、ProjectGrant 和账户绑定。 +6. 工具参数中的 `user_id`、role、project grant 和 review mode 均不具备权威性。 +7. 会话过期、用户停用、绑定失效或权限版本变化后，新调用立即失败。 + +飞书 token、MCP access token 和 Gitea token 互不透传。MCP Server 调用 Gitea 时使用自己的项目级凭据或受控 Gitea 适配器。 + +## 7. 双层权限 + +```text +Allow = AuthenticatedFeishuUser + ∩ ActiveInternalIdentity + ∩ AgentSession + ∩ InternalProjectGrant + ∩ ActionPolicy + ∩ ResourceScope + ∩ Content/SensitivityPolicy + ∩ GiteaProjectPermission + ∩ HumanConfirmationWhenRequired +``` + +### 7.1 第一层：内部权限数据库 + +判断用户是否属于业务线和项目、承担什么角色、可以执行哪些 MCP action、是否到期或已撤权。它是用户业务权限的第一层真源。 + +### 7.2 第二层：Gitea 项目权限 + +读取前复核用户绑定的 Gitea 账户是否仍具备目标项目读取资格。发布时复核用户仍是目标项目成员并具有 publisher 业务角色；真正写 `main` 的仍是项目级 `publish-gateway` 服务身份。 + +Gitea 不需要允许普通用户直接写 `main`。commit、release 和审计记录必须保留 human/agent/service 三主体归因，不能把服务账号误记为业务发起人。 + +### 7.3 失败策略 + +- 任一层拒绝均 fail closed；不能改用共享账号或更高权限 MCP。 +- 内部数据库与 Gitea 权限不一致时，按拒绝处理并记录 `permission_mismatch`。 +- 用户从项目撤权后，MCP 读取、搜索、构建和发布未来访问同时失效。 +- 不能先跨项目检索后在模型端过滤；必须先服务端鉴权再查询。 + +## 8. MCP 工具面 + +### 8.1 身份与项目 + +- `get_my_identity` +- `list_authorized_projects` +- `get_my_project_roles` + +### 8.2 Current 读取 + +- `get_current_manifest` +- `read_artifact` +- `search_current` +- `verify_release_hash` + +### 8.3 构建与预览 + +- `create_selection` +- `build_preview` +- `validate_release_request` +- `preview_release_diff` + +这些工具不产生远端状态，可以在用户授权来源范围内由 Agent 执行。 + +### 8.4 发布 + +- `submit_discussion_release` +- `submit_confirmed_release` +- `get_release_status` +- `cancel_precommit_release` + +提交工具必须绑定用户、项目、action、candidate hash、`base_current`、AgentSession 和精确人类确认。MCP 只提交受控请求；发布网关读取服务端策略并执行事务。 + +### 8.5 审计查询 + +- `list_my_actions` +- `get_action_detail` +- `trace_release` +- `trace_correlation` +- `list_project_audit_events`（仅项目维护者/审计角色） +- `verify_audit_event` + +### 8.6 明确不暴露 + +- 审计写入、修改或删除； +- Gitea 全局管理、直接 Git push、历史重写； +- SSH shell、生产部署、服务重启； +- 数据库迁移和任意 SQL； +- 备份删除/恢复； +- 密钥读取、导出和轮换； +- 权限数据库直接写入； +- 审核策略和动作开关修改。 + +上述能力属于运维或治理控制面，不能因为“全员 Agent”而成为普通 MCP 工具。 + +## 9. Agent 能力与人类确认 + +| 能力 | v1.1 默认 | 人类要求 | +|---|---|---| +| A1 current 读取/搜索 | 允许 | 登录用户已有项目读取权 | +| A2 selection、构建、检查、diff | 允许 | 来源范围由用户明确选择或授权 | +| A3 discussion 发布请求 | 允许受控调用 | 每次绑定目标、hash、项目和确认 | +| A4 confirmed/恢复请求 | 允许调用网关，不允许直接生效 | 精确确认；内容审核和高风险授权继续分开 | +| A5 成员、密钥、删除、策略、全局管理 | 禁止 | 不向普通 Agent 暴露 | + +Agent 不是发布凭据持有者。Agent 的作用是代表已登录用户调用受控 MCP 工具，不能自授角色、切换用户或改变确认内容。 + +## 10. 强制审计 + +### 10.1 三主体行为链 + +每次操作必须分别记录： + +- `human_actor`：发起操作的内部用户和飞书绑定； +- `agent_actor`：Agent、Host、client、session 和运行配置； +- `service_actor`：实际执行读取、网关、Gitea、导出或审计写入的服务身份。 + +### 10.2 审计事件字段 + +```yaml +event_id: "evt_" +event_type: "mcp.tool.completed" +occurred_at: "" +correlation_id: "" +session_id: "" +human_actor: + user_id: "human:" + feishu_tenant: "" + feishu_open_id_hash: "sha256:" +agent_actor: + agent_id: "agent:" + mcp_client_id: "" + runtime_version: "" +service_actor: + service_id: "service:" +business_line_id: "" +project_id: "" +tool_name: "" +action: "read | search | build | validate | publish | cancel | audit_read" +resource: + type: "" + id: "" +request_hash: "sha256:" +policy_version: "" +authorization_result: "allowed | denied" +confirmation_id: "" +release_id: "" +remote_version: "" +result: "completed | denied | failed" +error_code: "" +details_hash: "sha256:" +``` + +正文、原始 Prompt、token、cookie、私钥、密码和完整敏感参数不进入审计；只记录资源标识、脱敏摘要和 hash。 + +### 10.3 写入机制 + +审计不是 Agent 主动调用的工具。MCP Gateway 中间件自动执行： + +```text +验证连接身份 + → 写 request_received + → 双层权限和策略判断 + → 写 allowed/denied + → 执行业务动作 + → postcheck/readback + → 写 completed/failed + → 返回 Agent +``` + +- 审计存储使用 append-only 接口；普通业务模块无 update/delete 权限。 +- 发布、权限、确认、策略和其他写操作在审计不可持久化时 fail closed。 +- 读取操作先写可靠本地队列；队列也不可用时拒绝执行，不能产生无审计读取。 +- 审计事件写入与业务状态使用 outbox/等价机制关联，避免“动作成功但事件丢失”。 +- 审计查询可以通过 MCP，审计写入永不作为普通 MCP tool 暴露。 + +## 11. 无自建 Web 页面 + +v1.1 不建设发布驾驶舱、权限管理后台、审计后台或自定义登录页： + +- 日常交互界面：现有 Agent Host； +- 用户身份认证：飞书现有授权/登录页面； +- 敏感工具确认：Agent Host 的确认交互； +- 知识读取、构建、发布和审计查询：MCP； +- 少量技术管理：受控配置、运维任务和 Gitea 自带管理员界面。 + +“无自建 Web 页面”不表示没有 HTTP。公司全员访问使用远程 MCP transport；开发阶段可使用 STDIO。传输层、OAuth 回调和 Gitea 自带页面不属于本项目自建业务 Web 页面。 + +## 12. 运维控制面例外 + +以下流程不能纳入普通用户 MCP 工具，但仍必须审计： + +- 部署、升级、服务启停和数据库迁移； +- 备份、完整恢复和灾难演练； +- 密钥生成、读取、轮换和吊销； +- Gitea 全局管理员动作； +- 审计保留策略和事件销毁； +- 权限规则、动作开关和审核策略变更； +- 敏感历史重写和事故处置。 + +它们走独立运维/治理任务，产生同一 audit schema 的 operation 事件；普通 Agent 只能查询授权范围内的结果。 + +## 13. 保持不变的 v1 原则 + +- 一项目一私有 Context 仓库； +- 私人来源到企业 current 单向明确发布； +- 发布网关唯一写 `main`； +- `main/current` 唯一默认读取面； +- 内容状态和 release 状态分离； +- `base_current` CAS、幂等、原子切换和发布后读回； +- 试点审核 `forced_off`； +- 恢复旧内容必须形成新 release； +- 未授权项目、历史、staging、私人来源和控制面不进入 Agent Context； +- 飞书只承担身份，不在本版本承担内容来源、审批平台或知识库真源。 + +## 14. 实施与迁移原则 + +1. 先实现身份绑定、MCP Gateway 骨架和强制审计，再开放业务工具。 +2. 先开放 `get_my_identity` 和只读 current 工具，验证逐用户身份和双层权限。 +3. 再开放构建、验证和 diff 等无远端状态工具。 +4. 最后开放发布请求工具；每次写请求需要精确人类确认、网关事务和读回。 +5. 不提供从 MCP 失败自动回退到共享 CLI、通用 Gitea token 或直接 shell 的路径。 +6. 不要求普通成员迁移到自建 Web 系统；Agent Host 是唯一日常入口。 + +## 15. 验收标准 + +- 两名不同飞书用户通过同一 Agent Host 调用工具时，审计主体、项目列表和权限结果不同且正确。 +- 用户不能通过工具参数冒充其他 `user_id`、role、project grant 或 AgentSession。 +- 内部权限允许但 Gitea 权限拒绝、以及相反场景，均 fail closed 并产生 `permission_mismatch`。 +- 每次 read/search/build/validate/publish/cancel/denied 都能查到 human＋agent＋service 行为链。 +- 发布 commit 使用网关服务身份执行，但可追溯到精确用户确认和 AgentSession。 +- 停用用户、解除飞书绑定、移除项目授权或撤销 Gitea 成员后，未来 MCP 访问立即失败。 +- 普通用户无法调用审计写入/删除、权限写入、Gitea Admin、SSH、部署、备份和密钥工具。 +- MCP 不可用时不会回退到更高权限通道。 +- 不建设自定义业务 Web 页面，真实成员仍能通过 Agent 完成身份确认、读取、构建、发布和查询自己的审计记录。 +- 原 v1 的唯一 current、CAS、幂等、原子切换、状态语义和读回测试继续全部通过。 + +## 16. 进入代码开发前仍需确认 + +以下是 C1 技术选择，不影响本文架构成立： + +- 全员使用的 Agent Host 与其飞书登录集成方式； +- MCP Server 编程语言、官方/兼容 SDK 和最低协议版本； +- 远程 MCP transport、OAuth/身份代理和 token 生命周期； +- 身份权限数据库与 audit store 的具体技术产品； +- Agent Host 对 A3/A4 工具确认的交互能力； +- 审计保留期限、查询范围、脱敏规则和安全责任人； +- Gitea 权限复核使用 API、缓存和失效机制； +- 断网、飞书不可用、MCP 不可用时允许的只读降级策略。 + +这些事项确认前可以继续完善设计，但不能创建真实身份绑定、远程 MCP、权限数据库或审计生产资源。 diff --git a/Gitea知识库/公司共享 Context 项目仓库发布方案 v1.md b/Gitea知识库/公司共享 Context 项目仓库发布方案 v1.md new file mode 100644 index 0000000..b0df889 --- /dev/null +++ b/Gitea知识库/公司共享 Context 项目仓库发布方案 v1.md @@ -0,0 +1,645 @@ +--- +title: 公司共享 Context 项目仓库发布方案 v1 +date: 2026-08-03 +type: 设计spec +status: published +content_status: confirmed +belongs_to: + - "[[3-业务线/Gitea知识库/_context|Gitea知识库]]" +owner: Verlit +last_modified_at: 2026-08-06T18:24:55+08:00 +last_modified_by: Codex +migrated_from: "0-收集箱/公司共享 Context 项目仓库发布方案 v1.md" +governance_overlay: "[[2026-08-03-v1审核开关治理模型_deepseek-v4-pro]]" +hash: "sha256:a3a33cec7dfd0441fdf12af420bfc4f3d63ee7c113d4ae298ab96d2e2e45285f" +hash_scope: "Markdown 正文（从一级标题开始至文件末尾）的 UTF-8 SHA-256" +--- + +# 公司共享 Context 项目仓库发布方案 v1 + +> **一页纸结论** +> 本方案不重新发明知识同步系统，而是以 2026\-07\-28 采集的“四人 Obsidian \+ Git \+ Nginx”分享方案为 v0，保留 Git 留痕、服务器只读和 Agent 接入，补上五个企业项目必需的差分：**按项目组织、散落来源发布、统一 current、按项目授权、发布后回读**。 +> +> v1 的核心原则是：**项目是公司共享知识的业务容器，仓库是权限容器；个人怎么创作和留历史由个人决定，经过明确发布进入公司自建 Gitea 项目仓库 ****`main/current`**** 的内容，才进入公司共享读取面并被 Agent 默认读取；其中 ****`content_status: confirmed`**** 才代表已经确定的公司口径，****`discussion`**** 只代表当前在途材料。confirmed 是否需要第二人审核由项目审核策略决定；试点固定为 `forced_off`，仍保持发布即生效。** +> +> + +> **当前版本身份** +> +> - 本文是 AI组织 W30“公司共享 Context 实现方案设计”的**当前设计真源**。 +> +> - 方案已经定稿，个人 `cc` Vault 的 Markdown\-only Git 基线已经建立；公司 Gitea、首个项目仓库、只读入口和发布 Skill 尚未部署。 +> +> - 当前团队共 6 人；v1 仍只选择 1 个项目试点，项目成员从 6 人中按实际权限确定。6 人是当前组织事实，**不构成所有项目必须全员加入或企业知识库永久只服务固定人群的业务硬门**。 +> +> - 外部案例和调研报告是证据，不替代本文的实施口径。 +> +> + +## 版本边界 + +|版本|只解决什么|暂不解决什么| +|---|---|---| +|v1：发布链|选择材料、标记 `discussion / confirmed`、按项目审核策略决定 confirmed 是否待审核、写入项目 `main/current`、导出、通知与 Agent 读回、Git 恢复|不建设通用审批平台、proposal/PR、多级会签或飞书审批；试点审核策略固定关闭| +|v2：治理增强候选|根据 v1 的真实使用摩擦，选择正式审批集成、飞书权限、跨项目治理或保持轻量开关|不预设一定同时建设，也不在 v1 前置实现| + +v1 可以在发布前由发布者自行查看 diff，也可以在线下或飞书里讨论重大修改。项目策略为 `forced_off` 时，这些行为不构成第二道批准门；策略有效开启时，confirmed release 进入 `pending_review`，由 reviewer 对不可变候选 hash 作出决定。`pending_review` 是发布事务状态，不是第三种内容状态。发布前的结构、链接、附件、隐私和凭据检查是**质量检查**，不是内容审核。 + +## 方案全景 + +最终方案由五个边界组成： + +1. **个人工作区**：保留每个人现有的 Obsidian、本地目录、飞书、Notion 或其他工具，不强制创建个人 Git 仓库；当前 `cc` Vault 已选择“本地 Git 留历史 \+ NAS 单向备份”。 + +2. **发布入口**：个人明确选择允许共享的文件、段落或多份材料，生成项目级发布物。 + +3. **项目仓库**：公司在空余服务器上自建 Gitea，按项目建立私有仓库并按项目成员授权；发布动作直接更新仓库 `main/current`。 + +4. **只读 current**：服务器只导出已发布的 current，管理层和 Agent 从统一入口读取。 + +5. **历史账本**：Git 保存差异和恢复点，但历史、草稿和私人来源不进入 Agent 默认读取面。 + +## 一、方案来源：以外部分享为 v0，只保留真实增量 + +本方案的技术底座来自 2026\-07\-28 采集的飞书分享。原方案已经证明以下链路在四人小团队中可以运行： + +- 每个人保留自己的 Obsidian Vault； + +- 只同步指定团队内容，不默认暴露整个 Vault； + +- Git 承担同步与版本历史； + +- bare Git \+ `post-receive` 导出工作树； + +- Nginx 提供 Markdown 只读访问； + +- Agent 通过 HTTP \+ Basic Auth 读取； + +- Skill/安装包封装 Git 和路径细节。 + +wide 调研没有发现一条完全不同、又能原生解决全部问题的新架构。它的价值是验证原方案方向成立，并给出原方案没有覆盖的真实失败模式。v1 因此只做以下差分： + +|v0 外部分享|v1 公司方案| +|---|---| +|按成员汇集多个个人仓库|按公司项目建立共享仓库| +|只同步预先集中的团队子目录|允许从散落文件、段落和多份材料生成发布物| +|任意 push 后立即展示|只有显式“发布”动作能更新 current；confirmed 是否审核由项目策略决定，试点固定免审| +|Agent 读取服务器检出的内容|Agent 只读已发布的 current 快照| +|Basic Auth 粗粒度共享|项目仓库按项目成员授权，Agent 使用独立只读身份| +|Git 历史即全部版本|current 与历史读取面分离| +|协作状态未区分|v1 在 current 内增加 `discussion / confirmed` 材料状态；审核开启时只增加 release 事务状态，不增加内容状态| +|未覆盖通知与刷新确认|每次发布生成回执并做 Agent 读回| + +## 二、七条最终原则 + +1. **项目是公司共享知识的基本对象。** + +2. **仓库按权限边界建立；v1 默认每个项目一个企业私有仓库。** + +3. **个人是否使用 Git、是否建立个人仓库，不做强制。** + +4. **个人工作区保存私人过程材料，项目仓库保存已明确共享的当前版本。** + +5. **个人材料通过单向发布进入项目仓库，不做双向同步。** + +6. **本地统一使用标准 Git；个人仓库留在本地并由 NAS 单向备份，公司项目仓库以自建 Gitea 作为远端和权限层。** + +7. **v1 以“明确发布”为共享生效动作；进入 ****`main/current`**** 的内容才进入公司共享读取面，其中只有 ****`confirmed`**** 能被人和 Agent 当作已经确定的公司口径；审核策略开启时，confirmed 必须先通过绑定候选 hash 的审核。** + +其中需要特别澄清： + +> “发布而不是复制”是权威关系的定义，不是说技术上完全不产生第二份文件。 +> +> + +发布会物理生成一份企业共享产物，但个人材料与企业产物不是两个竞争真源： + +- 个人材料是原料、过程稿和个人工作上下文； + +- 项目仓库 current 是公司当前共享读取面，不自动等于已经定稿； + +- `current + discussion` 是正在协作的在途材料，Agent 必须显式标注状态，不能把它表述为公司结论； + +- `current + confirmed` 是已经确定、可被人和 Agent 作为公司口径引用的材料； + +- 个人材料发生变化，不会自动覆盖企业 current； + +- 企业 current 只有经过下一次明确发布才能更新； + +- 项目审核策略为 `forced_off` 时不要求第二个人批准，发布权限本身就是生效权限；策略有效开启时，confirmed 必须由 reviewer 审核不可变候选； + +- 企业 current 的修改若需回到个人原稿，通过建议或人工吸收处理，不做自动反向同步。 + +## 三、总体架构 + +### 3\.1 个人边界 + +- 不要求统一个人目录； + +- 不要求个人仓库； + +- 不把整个个人 Vault 暴露给公司 Agent； + +- 发布 Skill 只读取本次明确选择的来源； + +- 临时构建发生在 vault 外的临时目录，不在私人源目录内生成派生文件； + +- 绝不把私人仓库历史直接提升为公司共享历史。 + +当前 `E:/local_project/cc` 的个人实现已经确定为： + +- Vault 根目录建立一个本地 Git 仓库，只纳入选定的 Markdown 与仓库规则文件；历史基线 commit 为 `ab9496768cb8df6c59b615996269e3f06dbe2290`； + +- `2-代码库/` 等独立代码仓库和 `7-飞书镜像/` 不进入 Vault 根仓库；子仓库由离目标文件最近的 `.git` 独立提交； + +- 一次业务变化若同时修改代码和知识文档，分别在代码仓库与 Vault 仓库提交，必要时用同一任务 ID 关联，不追求跨仓库“一个 commit”； + +- Vault 到 NAS 只做单向备份，不做双向同步；NAS 必须包含 `.git` 或定期保存 `git bundle`，否则只能恢复文件现状，不能恢复 Git 历史； + +- 个人 Vault 不推送到公司 Gitea。公司 Context 项目仓库应放在根仓库明确排除的位置（如 `2-代码库/-context/`）或 Vault 外，避免父子仓库同时追踪同一文件。 + +- Claude Code 与 Codex 已接入项目本地的 session\-aware checkpoint 软提醒：只记录当前 session 通过文件写入工具明确触碰的 Markdown，在完成前提醒精确 commit；不自动暂存、不自动提交，也不把其他会话的全局脏状态归给当前 session。两端都需要新会话加载，Codex 首次加载时需通过 `/hooks` 审阅并信任项目 hook。 + +以上是当前 `cc` Vault 的具体落地，不是强制所有成员都采用个人 Git。对其他成员，v1 只要求能从其现有工作区明确选择材料并发布。 + +### 3\.2 项目仓库边界 + +项目是业务容器，仓库是权限容器。v1 采用一项目一仓，原因是用户已经确认需要按项目给不同人授权，而 Git 最可靠的权限边界是整个仓库。公司远端明确使用自建 Gitea：它是独立开源的 Git 托管与权限管理系统，不是 Gitee；本地仍然使用标准 Git，只是公司项目仓库统一推送到 Gitea。 + +未来只有在多个项目的成员、保密级别和生命周期完全一致时，才可以评估合并仓库；不能因为目录看起来方便，就在同一仓库内用文件夹模拟安全隔离。 + +### 3\.3 公司读取边界 + +- 管理层按项目获得仓库权限； + +- Agent 不直接获得 Git 写权限； + +- Agent 默认不获得 `.git`、构建区和私人来源； + +- 服务器只导出 `main/current`； + +- 每个项目使用独立 current 地址或独立挂载路径； + +- 需要调查历史时，走显式历史查询，不把历史长期混入默认 Context。 + +## 四、权限模型 + +### 4\.1 角色 + +|角色|主要权限|明确禁止| +|---|---|---| +|个人作者|维护个人材料、选择发布来源|不能让个人修改自动覆盖 current| +|发布者|查看 diff、执行发布、获得发布回执|不能读取本次未选择的私人材料| +|项目维护者|管理 Gitea 项目成员、发布凭据、备份和恢复动作|不应静默改写 Git 历史| +|项目成员|使用独立 Gitea 账号与 SSH key，读取 current、查看被授权的项目历史|不能共享账号或访问未授权项目| +|Agent|读取 current 快照、返回版本信息|无私人源、历史和发布权限| + +同一个人可以同时担任作者、发布者和项目维护者。试点 `forced_off` 不强制把“提出修改”和“内容生效”拆成两个人的动作；项目审核策略有效开启时，publisher 与 reviewer 默认必须是不同人，并由系统记录绑定候选 hash 的审核决定。 + +### 4\.2 权限执行位置 + +|权限|执行位置| +|---|---| +|谁能看私人原稿|个人工作区与设备权限| +|谁能访问某项目|Gitea 项目仓库成员或项目团队| +|谁能执行发布|发布入口身份或发布网关凭据| +|谁能更新 `main`|仅发布网关对应的 Gitea 凭据；成员不直接 push `main`| +|谁能看 current|Nginx/只读挂载的项目身份| +|Agent 能读什么|current 导出根目录与独立只读凭据| + +frontmatter 或 manifest 中的 `audience` 只是权限说明，不是实际权限。真实执行必须依赖仓库成员、凭据和读取入口。 + +### 4\.3 权限撤回边界 + +Git 权限只能阻止未来访问，不能让已经 clone 到个人设备的历史自动消失。因此实施时必须同时规定： + +- 公司资料和职务产出仍属公司资产； + +- 离职或退出项目时移除仓库成员、吊销凭据； + +- 轮换共享读取凭据； + +- 不把敏感信息写入不必要的历史； + +- 设备和备份按公司规则处理； + +- 需要更高隔离的项目使用独立仓库，不能只删文件夹权限。 + +## 五、项目仓库结构 + +```text +-context/ +├─ README.md +├─ current/ +│ ├─ context.md +│ ├─ decisions/ +│ ├─ assets/ +│ └─ _release.yaml +├─ schema/ +│ └─ context.schema.yaml +└─ .gitignore +``` + +### 5\.1 `current/` + +这是人和 Agent 的默认读取根，只放已经发布、当前仍然有效的内容。 + +- `context.md`：能够独立理解的完整项目 Context； + +- `decisions/`：仍然生效、需要单独引用的重要决定； + +- `assets/`：current 实际依赖的附件； + +- `_release.yaml`：当前版本、材料状态、发布者、发布时间、来源谱系和替代关系。 + +### 5\.2 历史与发布构建 + +- 发布构建在 vault 外临时目录完成，成功发布或失败退出后均不进入 Agent 读取面； + +- v1 不要求 proposal 分支、PR/MR 或通用审批平台；仅当项目审核策略有效开启时保存精确 release 审核记录； + +- 被替代版本首先由 Git commit/tag 承担，不默认复制到 `current/archive/`； + +- 如业务确需保留归档正文，必须放在 Agent 默认读取根之外，并明确 `archived`； + +- 恢复旧版时不是让成员长期 checkout 旧 commit，而是重新发布一个新的 current commit。 + +### 5\.3 最小发布元数据 + +```yaml +project_id: "<稳定项目ID>" +artifact_id: "<稳定Context ID>" +maintainer: "<项目维护者>" +content_status: "discussion | confirmed" +published_revision: "" +published_by: "<发布者>" +published_at: "<发布时间>" +source_refs: + - source_id: "<来源标识>" + selection: "<文件/章节/片段>" +supersedes: "<被替代版本>" +audience: "<项目成员组>" +``` + +这些字段记录来源和生效关系，不公开个人设备上的绝对路径，也不把私人目录结构变成公司契约。`content_status` 按 `artifact_id` 记录；若一次发布中同时包含讨论态与已确定内容，应拆成不同 artifact，不允许用一个总状态掩盖混合语义。项目审核策略开启且 release 含任一 confirmed artifact 时，整个原子 release 等待审核，避免部分内容先行生效。 + +## 六、发布流程 + +### 6\.1 选择来源 + +发布者明确给出： + +- 目标项目； + +- 来源文件或对象； + +- 选择整个文件、指定章节还是指定片段； + +- 是否需要合并多份材料； + +- 本次发布物的 `content_status` 是 `discussion` 还是 `confirmed`； + +- 哪些内容明确不得进入共享区。 + +v1 不自动监听私人文件变化。私人源更新只产生“可能需要再发布”的信号，不自动覆盖 current。 + +### 6\.2 生成发布物 + +发布 Skill 在临时构建区生成一份干净发布物，并执行： + +- 只复制明确 allowlist 的正文； + +- 收集候选真正依赖的附件； + +- 把可发布的内部链接改写为项目链接； + +- 对未发布链接做删除、摘要替换或显式缺口标记； + +- 检查敏感信息、私人绝对路径和凭据； + +- 记录 `source_refs` 与内容 hash； + +- 生成 current 与本次发布物的 diff。 + +### 6\.3 发布 + +自动质量检查通过后，发布者确认目标项目和 diff，执行一次明确的“发布”动作。v1 的生效规则是： + +- 发布权限由项目发布身份或发布网关凭据控制； + +- 依据项目审核策略决定 confirmed 是否需要第二人审核；审核状态只存在于 release 事务，不创建第三种内容状态； + +- 发布者必须明确选择 `content_status`；改变材料状态也通过一次新的明确发布完成； + +- 自动检查失败时阻止写入，并保留上一版 current； + +- 发布网关校验本次构建所基于的 current hash，避免覆盖别人刚刚发布的新版本； + +- 发布成功后直接形成新的 `main/current` commit。 + +人工查看 diff、口头确认或飞书讨论可以存在。是否进入系统审核门由项目策略唯一决定；v1 只实现最小条件分支，不建设通用审批产品。飞书审批、复杂会签等产品化能力留给 v2 根据真实使用情况决定。 + +### 6\.4 生效与读回 + +发布物进入 `main/current` 后，该次更新完成一个版本切换： + +- 上一 current 在切换前持续服务； + +- 新 current 原子生效； + +- 旧版本退出默认读取面； + +- 发布回执记录替代关系； + +- current 导出完成后才进入读回和通知。 + +## 七、状态机 + +### 7\.1 两条状态轴 + +v1 把两件事分开： + +- **技术状态**回答“这是不是当前共享版本”：`current / superseded / retired`； + +- **材料状态**回答“内容是否已经确定”：`discussion / confirmed`。 + +两种材料状态都可以进入 current。发布者选择状态，系统记录并展示；discussion 永远免内容审核，confirmed 按项目策略决定是否需要 reviewer。状态变化必须形成新的发布记录，不能只在读取端口头改称呼。 + +需要区分四件事： + +- **私人材料存在**：不代表公司知道； + +- **发布物已经生成**：不代表已经进入公司 current； + +- **内容进入 current**：不代表已经定稿，仍要看 `content_status`； + +- **发布动作成功**：不代表导出和 Agent 已刷新； + +- **Agent 已读回**：只证明交付链正确，不证明业务判断永远正确。 + +## 八、通知与读回 + +每次发布生成一张发布回执，至少包含： + +- 项目与 current 地址； + +- 新 commit/hash； + +- 发布人和发布时间； + +- 变更摘要； + +- 被替代版本； + +- 需要关注的关键变化； + +- `content_status`； + +- Agent 读回结果。 + +v1 不依赖飞书 API 自动通知。第一期可以由发布者把回执和 current 链接人工发到现有协作群；待基础链路真实被使用后，再选择通知适配器。 + +发布完成必须验证： + +1. Git `main` 指向本次发布 hash； + +2. current 导出目录与 `main/current` 一致； + +3. Nginx/挂载入口能读到新版本； + +4. Agent 能返回正确 `artifact_id`、commit/hash、`content_status` 和关键结论；遇到 `discussion` 必须标注“在讨论中”，不能把它表述为已确定公司口径； + +5. Agent 默认读取不到发布构建区、历史和未授权项目。 + +任何一步失败，都不能报告“发布完成”。 + +## 九、恢复与冲突 + +### 9\.1 恢复 + +恢复不是让每个人各自停在一个旧版本，而是： + +1. 项目维护者或发布者选择一个历史 commit； + +2. 生成恢复发布物； + +3. 说明恢复原因和影响； + +4. 按正常发布流程形成一个新的 current commit； + +5. 导出并完成 Agent 读回。 + +这样公司始终只有一个 current，同时保留“为什么恢复”的谱系。 + +### 9\.2 冲突 + +|冲突类型|处理方式| +|---|---| +|两人同时执行发布|发布网关比较 `base_current`；后到且基线过期的发布失败，基于最新 current 重新构建| +|新内容补充旧内容|合入现有章节或新增章节，不必升级全部定义| +|新口径替代旧定义|形成完整新 current，旧版由 Git 历史保留| +|发布构建期间 current 变化|阻止覆盖，重新基于最新 current 生成 diff 后发布| +|私人源与企业 current 不一致|企业使用 current；私人源变化需再次发布| +|企业 current 需要反哺个人源|形成建议，由个人决定吸收，不自动回写| + +## 十、实现选择 + +公司实现已经明确选择**在现有空余服务器上自建 Gitea**，不再把 Git 品牌留作实施时待选项： + +1. Gitea 作为公司 Git 远端和权限层，管理 6 名成员的独立账号、SSH key、项目团队和私有仓库；每个项目只授权实际参与成员； + +2. 所有电脑仍使用标准 Git。个人 Vault 不设置公司远端，只由 NAS 单向备份，不上传公司 Gitea；公司 Context 项目仓库才推送到 Gitea； + +3. Gitee 免费团队方案在当前 6 人规模下不适合作为长期基础设施；自建 Gitea 不受托管平台套餐人数限制，但公司自行承担运维； + +4. 外部分享中的 bare Git \+ hook \+ Nginx 继续作为 v0 证据，不作为公司的长期权限管理层；裸仓库缺少用户、项目成员、密钥撤销和审计管理界面； + +5. 不选择 GitLab：对当前 6 人、Markdown 为主的负载过重；也不先部署重型 Wiki、Redis、对象存储或复杂页面权限系统； + +6. 所有项目采用单一发布网关：成员执行发布，只有网关的 Gitea 凭据能更新 `main`；网关同时执行项目审核策略，但不扩展为通用审批平台； + +7. Gitea 的仓库数据、数据库和配置必须做异机备份并至少验证一次恢复；NAS 是候选备份目标，但服务器到 NAS 的实际路径和 `.git` 纳入情况仍需现场确认； + +8. 生产服务器的实现修改必须先查明部署路径，通过开发环境 → Gitea 远端真源 → 服务器部署，不直接改生产工作树。 + +最小运行组件： + +- 一台现有空余服务器（已知规格高于 2 核 2 GB）； + +- 自建 Gitea 与异机备份； + +- 项目仓库与成员权限； + +- 单一发布网关； + +- current 导出 hook； + +- Nginx 或本地只读挂载； + +- 发布 Skill； + +- current 读回检查。 + +## 十一、v1 试点 + +### 11\.1 范围 + +- 当前团队共 6 人，从中选择实际参与首个项目的成员，不默认 6 人全员获得每个项目权限； + +- 一个正在运行、确实需要共享 Context 的项目； + +- 一套公司自建 Gitea； + +- 一个 Gitea 项目私有仓库； + +- 一个项目维护者和至少一个发布者； + +- 不迁移历史全量知识； + +- 只实现按项目审核开关的最小条件分支；不建设通用审核工作流； + +- 不依赖飞书 API，也不打通飞书权限。 + +### 11\.2 五类样本 + +1. 私人单文件先以 `discussion` 发布，再重新以 `confirmed` 发布； + +2. 不同目录的多份材料合成； + +3. 带图片或附件； + +4. 相邻存在私密内容，只发布允许片段； + +5. 两人基于同一 current 并发发布，后到的旧基线发布被阻止并能在最新版本上重建。 + +### 11\.3 通过口径 + +- 未选择的私人内容和私人仓库历史未进入项目仓库； + +- 人和 Agent 都能识别同一个 current hash； + +- 人和 Agent 都能识别每个 artifact 的 `content_status`，且不会把 `discussion` 当成已确定结论； + +- 发布者能够在不处理 Git 分支和 PR/MR 的情况下完成发布； + +- 项目成员使用独立 Gitea 账号和 SSH key；移除成员后能够阻止其未来访问； + +- 发布构建与失败结果不进入默认读取面； + +- 附件、链接和项目内引用完整； + +- 能完成一次恢复发布并保持单一 current； + +- 项目成员不需要亲自处理复杂 Git 冲突； + +- 至少有真实发布、读取、纠错和恢复行为，而不是只完成安装； + +- 从空环境能够恢复正文、附件、历史和读取入口； + +- Gitea 仓库、数据库和配置完成异机备份，并至少验证一次恢复。 + +### 11\.4 止损信号 + +- 同一项目出现两个被人或 Agent 当作 current 的入口； + +- 私人内容进入共享历史且无法确认影响范围； + +- 每次发布都要手工修链接、附件或 merge； + +- 实际发布仍只有技术维护者使用，其他成员不参与； + +- Agent 必须扫描私人 Vault 或历史分支才能回答； + +- 发布权限和项目维护责任不清，却开始增加复杂服务和自动化； + +- 多人共享同一个 Gitea 账号或 SSH key，导致访问和撤权无法归人； + +- Gitea 只有同机数据、没有可验证的异机备份，或升级后无法恢复； + +- 方案的维护成本明显高于当前共享问题本身。 + +## 十二、实施阶段 + +|阶段|目标|主要产物|进入下一阶段的条件| +|---|---|---|---| +|0\. 方案冻结|确认本文和首个试点|当前方案、试点项目、维护者、发布者、成员|用户确认实施范围| +|1\. Gitea 基础层|建立公司远端与权限边界|Gitea、独立账号/SSH key、项目私有仓库、异机备份|权限撤回和备份恢复可验证| +|2\. 基础链路|跑通项目仓库到 current|受保护 `main`、导出、只读入口|人和 Agent 能读取同一 hash| +|3\. 发布入口|隐藏 Git 操作|发布 Skill、diff、发布网关、回执|发布者能一步更新 current| +|4\. 真实试点|验证协作而非安装|五类样本、发布回执、恢复记录|无止损信号，成员真实使用| +|5\. v2 判决|判断是否需要治理增强|正式审批集成、飞书权限需求、成本与收益证据|用户决定扩展正式治理、飞书集成或保持轻量开关| + +v2 不是默认的“完整版本”，而是一个由 v1 真实摩擦触发的选择：可能接入正式审批，可能只打通飞书权限，可能两者都做，也可能保持 v1 的轻量审核开关。manifest、自动编译、自动通知和更多项目仓库同样只由真实摩擦拉动。 + +## 十三、明确不做 + +- 不同步整个私人 Vault； + +- 不强制个人建立 Git 仓库； + +- 不把个人 Vault 推送到公司 Gitea； + +- 不用 submodule 拼接多个私人仓库； + +- 不做私人源与企业 current 的双向同步； + +- 不自动监听并发布私人文件变化； + +- 不在父仓库已追踪的路径中嵌套公司项目仓库，除非父仓库已明确排除； + +- 不在同一仓库内用文件夹模拟保密权限； + +- 不使用共享 Gitea 账号或共享 SSH key； + +- 不把 Gitee 免费版作为 6 人团队的长期权限层； + +- 不用纯 bare Git 长期承担公司用户与项目权限管理； + +- 不让 Agent 获得 Git 写权限或默认读取全部历史； + +- 不把“已进入 current”自动解释成“已经定稿”； + +- 不在 v1 建设 proposal、PR/MR、通用审批平台或多级会签；项目开关开启时仅保留 reviewer 和 release 审核状态； + +- 不在第一期部署重型企业 Wiki； + +- 不把飞书 API 或飞书权限打通作为首轮运行依赖； + +- 不一次覆盖所有项目。 + +## 十四、决策记录 + +|日期|已确认决定|来源| +|---|---|---| +|2026\-07\-24|项目立项即建立公司共享 Context；AI 默认只读 current；旧版可追溯恢复|项目知识库会议| +|2026\-07\-28|外部四人 Git/Nginx 方案作为轻量传输与读取 v0，不直接等同完整治理|外部方案评估案例| +|2026\-07\-28|wide 调研未发现完整一体化替代方案；Git 适合发布账本，不适合同步整个私人库|wide 调研报告| +|2026\-07\-29|项目作为业务对象；按项目授权时一项目一仓；个人仓库不强制；个人材料通过发布而非双向复制进入企业仓库|当前 Codex 会话| +|2026\-07\-29|用户批准把方案落到正式文档并整合 Mermaid 示意图|用户原话：“可以，你先把方案落到文档中，注意增加一些mermaid 示意图便于理解，然后整合最终文档”| +|2026\-07\-29|分版本推进：v1 淡化审核、只保留发布；v2 再考虑审核或打通飞书权限|用户原话：“分版本吧，第一个版本先淡化审核，只保留发布，下一个版本再考虑审核或者打通飞书权限”| +|2026\-07\-29|v1 增加材料状态：`current` 只表示当前共享版本，`discussion / confirmed` 区分在途内容与已确定口径；当时决定不增加审核|用户原话：“材料状态我同意，可以按照那个修改方案。”；该治理决定已被 2026-08-03 审核开关基线局部替代| +|2026\-08\-03|采用按项目审核开关；试点 `forced_off`，保留原 v1 免审行为，同时允许项目后续受控启用|用户要求基于 DeepSeek 审核开关治理模型核实、修正并最终收敛全部执行设计| +|2026\-07\-29|当前 `cc` Vault 建立 Markdown\-only 本地 Git 基线，`2-代码库/` 子仓库独立提交；Vault 到 NAS 只做单向备份|Vault 基线 commit `ab9496768cb8df6c59b615996269e3f06dbe2290`| +|2026\-07\-29|当前团队 6 人；公司远端选用空余服务器自建 Gitea，一项目一仓并按项目授权；个人 Vault 不上传公司 Gitea|用户原话：“好，我认可这个方案，现在更新方案文档吧”| + +## 十五、进入实施前仍需拍板 + +以下不是方案缺口，而是实际开工必须由用户给出的项目字段： + +1. 首个试点项目是什么； + +2. 6 人中哪些是首个项目的成员； + +3. 项目维护者与允许执行发布的人； + +4. 空余服务器的操作系统、网络入口、域名/HTTPS、磁盘和服务器到 NAS 的备份路径； + +5. 实施是否建立“驾驶舱”页面，用于显示阶段、信号灯、待拍板和止损状态。 + +在这些字段确认前，可以做环境盘点和实施清单，但不应替用户默认项目、人员或权限。 + +--- + +> **最终收口：个人怎么写由个人决定；当前 ****`cc`**** Vault 用本地 Git 留 Markdown 历史并单向备份到 NAS，个人 Vault 不上传公司远端；公司在空余服务器自建 Gitea，按项目建立私有仓库并授权，一次明确发布把选定材料送入 ****`main/current`****。Git 记录历史，Agent 只读取已发布的 current，并根据 ****`discussion / confirmed`**** 区分在途材料与已确定口径。confirmed 审核由项目策略控制，试点固定免审；正式审批平台和飞书权限仍属于 v2 候选，不阻塞 v1。** +> +>