---
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_<uuid>"
event_type: "mcp.tool.completed"
occurred_at: "<RFC3339>"
correlation_id: "<id>"
session_id: "<agent-session>"
human_actor:
  user_id: "human:<id>"
  feishu_tenant: "<tenant>"
  feishu_open_id_hash: "sha256:<hash>"
agent_actor:
  agent_id: "agent:<id>"
  mcp_client_id: "<client>"
  runtime_version: "<version>"
service_actor:
  service_id: "service:<id>"
business_line_id: "<stable-id>"
project_id: "<project>"
tool_name: "<mcp-tool>"
action: "read | search | build | validate | publish | cancel | audit_read"
resource:
  type: "<type>"
  id: "<id>"
request_hash: "sha256:<hash>"
policy_version: "<version>"
authorization_result: "allowed | denied"
confirmation_id: "<nullable>"
release_id: "<nullable>"
remote_version: "<nullable commit/hash>"
result: "completed | denied | failed"
error_code: "<nullable>"
details_hash: "sha256:<hash>"
```

正文、原始 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、权限数据库或审计生产资源。