---
id: project-capability-control-plane
name: 项目能力与交付控制面
status: planned
progress: 0
---

## 概述

炼境是被管理项目的工程管家，而非项目业务大脑或通用 CI 替代品。项目拥有业务规则、测试、迁移和部署要求；炼境保存云端环境与凭证引用，执行受控操作，采集运行证据。Enterprise System 是首个真实样板。

## 设计决策：项目能力协议与轻量交付控制面 v1

### 背景

Enterprise System 已有可用的云端交付基础：Gitea `main` CI 通过 SSH 调用服务器端 `deploy/deploy-api.sh`；脚本用 Git SHA 标记镜像，在停止旧容器前做环境/网络/镜像检查，切换后做容器内 HTTP 健康闸门，失败自动回滚，且保留近期镜像与 Gitea registry 回滚池。其关键缺口不是再造部署脚本，而是让 Agent 可安全发现、请求、验证和追溯这条能力。

### 方案选择

| 方案 | 说明 | 结论 |
| --- | --- | --- |
| 炼境直接内置每个项目的部署命令 | 快，但把项目细节、环境差异和业务风险硬编码进平台 | 否决 |
| 项目声明能力，炼境以 adapter 执行 | 项目保持自主，凭证与审计集中，能复用到异构项目 | **选定** |
| 强制所有 commit 经 PR/CI 后再部署 | 治理完整但阻塞 Agent 高频真实环境验证 | 否决；仅 production/高风险路径强制 |

### 系统边界

```
项目（Enterprise System）
  声明 verify/build/migrate/deploy/health/logs/rollback 的输入与成功断言
  保留 Dockerfile、migration、部署脚本和业务终验

炼境控制面
  保存环境、凭证引用、允许项目/目标、部署记录和运行证据
  通过 SSH / Docker Compose 等 adapter 执行受控动作

Gitea adapter
  提供 SHA、PR、少量 CI 与 release 依据；不是炼境核心依赖

Codex / Claude adapter
  读取项目规则与能力声明，调用炼境 MCP；不持有生产凭证
```

### 交付节奏

1. Agent 完成本地验证后小步 commit；多个相关 commit 汇成一个可说明的 PR／交付包。
2. 普通内部功能在 PR 合并后沿既有 Gitea CI 自动部署 production；炼境先采集版本、CI、健康与回滚证据，不替换项目部署脚本。
3. 涉及公共引擎、跨业务线、数据写路径或 migration 的改动进入 PR；Gitea CI 只保留高价值检查，并要求在 PR 中说明备份或回滚方式。
4. 炼境只呈现信号和执行受控操作，不判断业务是否“应该上线”；没有可验证的部署回传时必须明确标为 `unknown`。

### 协议草案

项目 canonical context 采用工具无关位置 `.lian-jing/context.json`；现有 `.claude/liangjing.json` 与 Codex 配置是派生兼容层。项目能力声明建议位于 `.lian-jing/capabilities.yaml`：

```yaml
version: 1
capabilities:
  verify:
    command: pnpm verify
  deploy:
    targets:
      production:
        adapter: ssh-script
        environment_ref: enterprise-production
        revision: git_sha
        command: bash deploy/deploy-api.sh
        requires_confirmation: true
  health:
    checks:
      - kind: http
        url_ref: enterprise-api
        expect_status: 401
```

声明不得包含 IP、SSH 私钥、数据库 URL 或 Secret。`environment_ref` 由炼境映射到加密保存的环境事实；adapter 命令采用 allowlist/模板参数，禁止 Agent 任意拼接远程 shell。

### 证据与失败模型

一次 deployment record 至少包含：`project_id`、`environment`、`requested_revision`、`resolved_sha`、`requester`、`started_at`、`finished_at`、`migration_set`、`adapter_result`、`health_evidence`、`previous_healthy_release`、`rollback_result`。任何外部源不可用都显式标为 unavailable/error，不能伪装成“无 PR”或“部署成功”。

### 验证路径

- 炼境：`cargo test` 直接调用 Git/Gitea 状态归并纯函数，断言脏工作区、无绑定、网络不可达和缺失部署证据均可诚实降级。
- Enterprise System：继续使用现有 production 部署脚本及其健康闸门/回滚；本阶段不把 production 当作自动测试路径。
- MCP：`get_delivery_status(project_id)` 返回本地 Git、Gitea、CI、review 与可取得的部署/health 来源状态，无错误字段时每项均可追溯。

### 现有链路的兼容策略

Enterprise System 当前 `push main → Gitea CI → deploy-api.sh` 是 production 链路，且服务器资源有限。本阶段保持该链路不动，也不引入常驻 staging。`get_delivery_status` 不将 CI 成功误报为线上健康；后续若线上验证成本或事故频率证明有必要，再以独立资源或按需环境增加 staging adapter。

### 风险点

- migration 非向后兼容：v1 不自动执行任意 migration；先读取项目声明、预检与锁定策略，production 必须人工确认。
- 无 staging 的生产验证风险：普通改动依赖本地验证、PR 和现有自动回滚；高风险 migration/关键数据改动要求备份和显式交付说明。
- Git SHA 与服务器工作树漂移：adapter 输出必须解析/回传 resolved SHA，且 health 证据绑定同一记录。
- 现有部署健康闸门仅证明 HTTP 监听：协议同时支持项目声明业务 health probe，不把存活探测误报为业务就绪。
- Gitea/网络故障：交付状态明确降级；项目本地验证与项目自有手工部署能力不受炼境阻断。

## 任务卡

### ✅ A. Canonical 项目上下文与 capability schema
- status: done
- complexity: M
- files: src-tauri/src/mcp_inject.rs, src-tauri/src/commands/onboarding.rs, src-tauri/src/mcp_tools.rs, src-tauri/resources/onboarding/, docs/templates/agents-meta-rules.md
- acceptance: "[cargo test] 旧 `.claude/liangjing.json` 项目重跑接入 → 写入 `.lian-jing/context.json`，project_id 一致；Claude/Codex adapter 均从 canonical context 派生且保留用户手工同名配置；无 canonical context 时给出可诊断兼容状态。"
- done_note: "2026-09-22：由 agent 复核确认与 P2-A 同一能力，canonical context、legacy 迁移、未知字段保留、手工同名 MCP 拒绝覆盖及诊断信号已在 PR #8/#9 完成；cargo test 139/139 与 Enterprise onboarding 12/12 已通过。"

### 📋 B. 炼境环境、授权与 deployment record 数据模型（后续受控执行）
- status: todo
- complexity: M
- depends: A. Canonical 项目上下文与 capability schema
- files: src-tauri/src/db.rs, src-tauri/src/models.rs, src-tauri/src/commands/
- acceptance: "[cargo test] in-memory DB 创建 environment / project authorization / deployment record 后，未授权项目、production 未确认、同环境并发请求均被拒绝；record 可记录 requested_sha、resolved_sha、health_evidence 与 previous_healthy_release。"

### 📋 C. SSH-script adapter 与生产环境锁（后续受控执行）
- status: todo
- complexity: M
- depends: B. 炼境环境、授权与 deployment record 数据模型
- files: src-tauri/src/commands/, src-tauri/src/lib.rs, src/lib/commands.ts
- acceptance: "[Tauri command] deploy_production(project_id, revision, confirmation) 对 mock SSH adapter → 仅接受声明中的 adapter/command，写入 running→succeeded|failed record；同一 environment_ref 第二次调用返回锁定状态，绝不执行第二条远程命令。"

### ✅ P1. 交付状态与 Gitea 轻量治理投影
- status: done
- complexity: M
- files: src-tauri/src/commands/gitea.rs, src-tauri/src/mcp_tools.rs, src-tauri/src/mcp_server.rs, docs/ai-context/
- acceptance: "[MCP tool] get_delivery_status(project_id) → 返回当前 SHA/工作树、PR/CI/review 来源状态与 deployment/health evidence 的已知或 unknown 状态；Gitea 不可达时标记 unavailable 而非把 PR 误报为空；cargo test 通过纯函数/命令级降级测试。"
- done_note: "2026-09-21：MCP schema/dispatch、Git/Gitea 聚合、接入说明和降级测试完成；production 部署回传尚未接入，按协议显式返回 unknown。"

### 📋 E. Enterprise System 可选 staging 隔离与部署 profile
- status: todo
- complexity: M
- depends: A. Canonical 项目上下文与 capability schema, C. SSH-script staging adapter 与环境锁
- files: E:/code-project/enterprise-system/deploy/deploy-api.sh, E:/code-project/enterprise-system/deploy/README.md, E:/code-project/enterprise-system/.gitea/workflows/, E:/code-project/enterprise-system/.env.api.example
- acceptance: "agent_verify: [future isolated staging] 部署已 push SHA → 使用与 production 不同的 environment_ref、服务器目录/容器名/域名/运行时配置，resolved SHA 和 health evidence 可读取；不触发既有 `push main` production job；human_verify: staging 关键业务接口可用。仅当资源与实际线上验证成本证明必要时启动。"

### 📋 F. Enterprise System capability 声明与可选 staging 适配验证
- status: todo
- complexity: M
- depends: E. Enterprise System 可选 staging 隔离与部署 profile
- files: E:/code-project/enterprise-system/.lian-jing/, E:/code-project/enterprise-system/deploy/README.md, E:/code-project/enterprise-system/.blueprint/
- acceptance: "agent_verify: [炼境 staging adapter] 请求 Enterprise System 已 push SHA → 只匹配声明的 staging profile，服务器输出 resolved SHA，容器 health gate 与项目声明的 HTTP probe 均通过，炼境 record 绑定同一 SHA；human_verify: staging 关键业务接口可用。"

### 📋 G. production 发布确认、回滚与操作报告（后续受控执行）
- status: todo
- complexity: M
- depends: C. SSH-script adapter 与生产环境锁（后续受控执行）, P1. 交付状态与 Gitea 轻量治理投影, F. Enterprise System capability 声明与可选 staging 适配验证
- files: src-tauri/src/commands/, src-tauri/src/mcp_tools.rs, src-tauri/src/commands/gitea.rs, E:/code-project/enterprise-system/deploy/
- acceptance: "[cargo test] deploy_production 缺显式 confirmation 或 required CI/PR evidence → 无远程执行；[adapter integration] health gate 失败 → record 标 failed 并保存 rollback result / previous release，生产成功记录含确认者与 resolved SHA。"

## 迭代衡量

首个版本上线后连续观察四周：commit 至 production 部署结果可追溯的时间、production 前实际拦截问题数、失败定位与回滚耗时、PR 等待时间、Agent 重复劳动/上下文丢失次数。不能降低任一真实成本的门禁或自动化应降级或移除。