lanrtop/dev-manager-tauri
1
0
Fork 0
Code Issues Pull Requests 2 Actions Packages Projects Releases Wiki Activity
1f38aebbac
dev-manager-tauri/.blueprint/modules/project-capability-control-plane.md
lanrtop 383b5b35d7
All checks were successful
Push & PR Check / check (push) Successful in 1m0s
Details
Push & PR Check / check (pull_request) Successful in 58s
Details
feat(delivery): add project delivery status 
Feature-Confirmed: true
2026-09-21 15:16:40 +09:00

10 KiB
Raw Blame History

id name status progress
project-capability-control-plane 项目能力与交付控制面 planned 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：

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: todo
  • 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 时给出可诊断兼容状态。"

📋 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 重复劳动/上下文丢失次数。不能降低任一真实成本的门禁或自动化应降级或移除。