docs(skill): rewrite deploy playbook — MCP first, never Dokploy UI

dokploy-gitea-deploy/SKILL.md

@@ -1,91 +1,102 @@
 ---
 name: dokploy-gitea-deploy
 description: >
-  企业项目部署：默认走 company-deploy-mcp（飞书身份 + buxi_ Key → 推 Gitea → MCP 建库/多卷/PG·MySQL/域名/HTTPS → 轮询）。
-  旧路径为直连 Dokploy API（.env.deploy），仅运维/无 MCP 时使用。触发词：部署、上线、Dokploy、Gitea、
-  redeploy、MCP 部署、buxi_、company-deploy-mcp。Use when /dokploy-gitea-deploy。
+  企业 Dockerfile 项目部署（唯一默认路径：company-deploy-mcp）。
+  飞书登录拿 buxi_ Key → 配置 MCP → whoami 联通 → ensure_repository + pushUrl 推代码
+  → create/apply plan → 轮询 → 交付 HTTPS 链接。用户永不进 Dokploy/Gitea。
+  触发：部署、上线、重部署、redeploy、查项目、配额、buxi_、company-deploy、企业部署。
+  禁止引导用户打开 Dokploy 面板或索要 DOKPLOY_API_KEY。Use when /dokploy-gitea-deploy。
 metadata:
-  short-description: "企业部署：优先 MCP，兼容 Dokploy 直连"
+  short-description: "企业部署：MCP 全流程（用户不进 Dokploy）"
 ---
 
-# 安装（给用户 / Agent）
+# 企业部署 Skill（company-deploy-mcp）
+
+## 0. 一句话
+
+**用户只做两件事：① 连接中心飞书登录拿 `buxi_` Key 配到 Agent；② 说「部署」。**  
+其余（建库、推代码凭据、挂卷、数据库、域名、HTTPS、构建）全部由 **Agent + MCP** 完成。
+
+| 正确 | 错误（禁止） |
+|------|----------------|
+| 调 MCP 工具部署 | 让用户打开 Dokploy 管理面板 |
+| 401 → 引导连接中心重拿 Key | 说「权限配置无法通过，去找管理员要 Dokploy 权限」 |
+| 交付 `https://buxi….loncode.site` | 索要 `DOKPLOY_API_KEY` / Gitea Token / 面板账号 |
+| 环境变量靠 plan（`databases[]` 等）或代码默认 | 让用户去 Dokploy 改某个应用的 env |
+
+**连接中心** `https://company-deploy-mcp.loncode.site/` = 飞书身份 + MCP 授权，**不是** Dokploy 面板。  
+**Dokploy** 只被控制面服务端调用，**业务用户与业务 Agent 默认不可见、不需要、不引导**。
+
+---
+
+## 1. 安装本 Skill（一次性）
 
 ```bash
-# 内网一键（推荐）
 curl -fsSL https://company-deploy-mcp.loncode.site/install-skill.sh | bash
-
-# 或 skills CLI
+# 或
 npx skills add http://git.loncode.site/Buxi/company-deploy-skills.git --skill dokploy-gitea-deploy -g -y
 ```
 
-技能仓：http://git.loncode.site/Buxi/company-deploy-skills  
-连接中心（飞书 + MCP Key）：https://company-deploy-mcp.loncode.site/
-
-Skill 只提供流程；真正部署还需配置 MCP `company-deploy`（`buxi_` Bearer）。
+Skill 只定义流程；**没有配置 MCP + `buxi_` Key 则无法部署**。
 
 ---
 
-# 企业部署编排（Gitea + Dokploy + company-deploy-mcp）
+## 2. 联通性检测（每次部署前必做）
 
-业务同学不碰平台细节。Agent 负责：可构建工程 → 推代码 → 调控制面 → 交付 **HTTPS 链接**。
+按顺序，**先测再部署**。任一步失败：按 §6 处理，**禁止**改口去要 Dokploy。
 
-**默认路径：company-deploy-mcp（必须优先）。**  
-直连 Dokploy API 为 **legacy / 运维例外**。
+### 2.1 MCP 是否挂上
 
-**产品范围（收口）：** 主路径是 **普通 Dockerfile 服务**（Python / Node / 静态站等）。  
-飞书 **妙搭 / `@lark-apaas/*` 模板不是主路径**——不承诺登录、权限、平台 API 与线上一致；控制面仅可能注入 **进程启动** 所需最小 env。详见 `references/stack-profiles.md` 支持矩阵。
+Agent 能否调用 `company-deploy` 的工具（至少 `whoami`）。
 
-参考：
+| 结果 | 含义 | 下一步 |
+|------|------|--------|
+| 工具列表里有 `whoami` / `apply_deployment_plan` | 已配置 MCP | → 2.2 |
+| 没有这些工具 / 调用直接失败 | 未配置或 Key 错误 | → §3 鉴权 |
 
-- `references/mcp-deploy.md` — **MCP 默认状态机**（工具参数、域名/卷/库）
-- `references/domain.md` — 域名与 HTTPS（Let’s Encrypt，无需通配符证书）
-- `references/sequence.md` — 时序
-- `references/env-deploy.example` — 仅 legacy 直连用
-- `references/stack-profiles.md` — Dockerfile 约定 + **支持矩阵**
-
-线上连接中心：`https://company-deploy-mcp.loncode.site/`  
-MCP endpoint：`https://company-deploy-mcp.loncode.site/mcp`
-
----
-
-## 路径选择
-
-| 条件 | 路径 |
-|------|------|
-| Agent 已配置 MCP `company-deploy`（`buxi_` Key） | **MCP 默认** |
-| 用户已飞书登录拿过 Key | **MCP 默认** |
-| 用户明确「不要 MCP / 运维直连 / 改 Dokploy 底层」 | legacy |
-| 无 MCP 且无 `.env.deploy` | **先引导连 MCP**，不要伪造部署 |
-
-**禁止**在可用 MCP 时仍让业务填写 `DOKPLOY_API_KEY` / Gitea Token。
-
----
-
-## 架构（默认）
+### 2.2 身份
 
 ```text
-用户：「部署 / 上线」
-  → Agent：Dockerfile + 本地验证
-  → Agent：ensure_repository（MCP）→ 拿到 agentHint.pushUrl（机器人 Token）
-  → Agent：git push <pushUrl>（禁止用用户 SSH；禁止向用户要密钥）
-  → Agent：create_deployment_plan + apply_deployment_plan
-       MCP 内部：挂卷 → PG/MySQL（可选）→ domain（buxi+5位.根域 + LE HTTPS）→ deploy
-  → Agent：get_deployment_status / list_projects 轮询
-  → 交付：https://buxi*****.loncode.site + 脱敏说明
+whoami
 ```
 
-- **飞书**：身份；**buxi_ Key**：调用 MCP  
-- **Gitea**：源码（**gitea-robot** 建仓+推送；业务用户**不需要** Gitea 账号或 `~/.ssh`）  
-- **Dokploy**：构建运行（由 MCP 调用，不直暴露给业务）  
-- **归属 / 配额 / 审计**：控制面 SQLite（`owner_open_id`、运行中数量）
+期望字段示例：`role`（`user`|`admin`）、`openId`、`name`、`isAdmin`。
+
+| 结果 | 处理 |
+|------|------|
+| 返回身份 JSON | 联通成功 |
+| 401 / Unauthorized / invalid token | Key 无效 → §3 |
+| 超时 / 连接失败 | 网络或控制面宕机 → 告之稍后重试，可 `curl -sS https://company-deploy-mcp.loncode.site/health` |
+
+### 2.3 配额
+
+```text
+get_my_quota
+```
+
+看运行中项目数是否达上限。满了：先 `list_projects`，让用户停/删不用的，**不要**绕过 MCP。
+
+### 2.4（可选）已有项目
+
+```text
+list_projects
+```
+
+重部署时记下已有 `repo` + `environment`（部署标签，默认多为 `default`），**必须沿用**，禁止擅自改成 `production`。
 
 ---
 
-## 前置条件
+## 3. 鉴权与获取授权
 
-### MCP 路径（默认）
+### 3.1 用户怎么拿 Key（业务同学）
 
-1. 用户已在连接中心飞书登录，Agent 已配置：
+1. 浏览器打开：**https://company-deploy-mcp.loncode.site/**
+2. **飞书登录**
+3. 复制页面上的 **`buxi_…` Key** 与 MCP 配置片段  
+4. 粘贴到 Agent 的 MCP 配置（见下）  
+5. 回到对话说「已配置」或直接「部署」
+
+### 3.2 Agent / 客户端怎么配
 
 ```json
 {
@@ -93,240 +104,286 @@ MCP endpoint：`https://company-deploy-mcp.loncode.site/mcp`
     "company-deploy": {
       "url": "https://company-deploy-mcp.loncode.site/mcp",
       "headers": {
-        "Authorization": "Bearer buxi_..."
+        "Authorization": "Bearer buxi_用户从连接中心复制的Key"
       }
     }
   }
 }
 ```
 
-2. 项目有可构建 **Dockerfile**（进程监听 `spec.port`，状态写 `/data` 等挂载点）  
-3. 本机有 `git` 即可；**推送凭据来自 `ensure_repository` 的 `agentHint.pushUrl`**，**不要**配置用户 SSH、**不要**加 `id_ed25519.pub` 到 Gitea  
-4. 企业侧已配：`*.DOMAIN_ROOT` DNS → Dokploy；80/443 可达（Let’s Encrypt）
+- 前缀：`buxi_`（旧 `cdp_` 可能仍可用，新发一律 `buxi_`）  
+- **禁止**把 Key 写进业务 Git 仓库  
+- **禁止**把 Key 完整打印在对用户的回复里（可确认「已配置」）
 
-无 Key：引导打开连接中心登录，**不要**继续直连 Dokploy。
+### 3.3 权限模型（Agent 必须理解）
 
-### Legacy 路径（运维）
+| 能力 | 谁有 | 说明 |
+|------|------|------|
+| 部署自己的项目 | 任意有效 `buxi_` | 首次 `apply` 建立归属 |
+| 看自己的项目列表/状态 | 自己 | `list_projects` / `get_deployment_status` |
+| 看别人的项目 | 仅 admin | `ADMIN_OPEN_IDS` 或平台 `MCP_AUTH_TOKEN` |
+| 进 Dokploy 面板 | **不在本产品路径** | **禁止**当作用户解决办法 |
+| 手改 Gitea 权限 / SSH | **不需要** | 推送只用 `ensure_repository` 的 `pushUrl` |
 
-见文末；需 `.env.deploy` + `DEPLOY_AUTHORIZED=true`。
+### 3.4 鉴权失败怎么说（固定话术）
+
+**401 / 未配置 MCP：**
+
+> 还不能部署：需要先完成企业部署授权。  
+> 1. 打开 https://company-deploy-mcp.loncode.site/  
+> 2. 飞书登录，复制 `buxi_` Key  
+> 3. 按页面说明粘贴到当前 Agent 的 MCP 配置  
+> 4. 配置好后回复「已配置」，我再继续部署。  
+> （连接中心只负责身份和 MCP，不需要 Dokploy 账号。）
+
+**403 看别人的项目：**
+
+> 当前账号只能管理自己名下的项目。如需管理员视角，请联系平台管理员把你的飞书 open_id 加入白名单。
+
+**禁止话术（截图类错误）：**
+
+- ❌「你不能通过项目网页进入 Dokploy」  
+- ❌「向管理员索取 Dokploy 面板地址 / 登录账号 / 某应用环境变量编辑权限」  
+- ❌「企业部署连接中心不是 Dokploy，所以你没法配 env——去找管理员开 Dokploy」  
+- ❌ 凭空编造 Dokploy URL  
+
+若用户要的是 **业务应用自定义密钥**（如第三方 API Key），而 plan 又注入不了：
+
+> 当前 MCP 会自动注入数据库连接（`databases[]`）和运行所需基础变量；  
+> **不提供**业务同学自助打开 Dokploy 改 env。  
+> 可选：① 非密钥配置进代码/配置文件；② 密钥由平台管理员走运维通道注入（不经过业务 Dokploy 账号）；③ 应用支持启动后自助配置页。  
+> **我不会让你去申请 Dokploy 面板权限。**
 
 ---
 
-## MCP 标准状态机（必须按序）
+## 4. 部署操作流程（默认全链路）
 
-细节与 JSON 示例见 `references/mcp-deploy.md`。
-
-### 0. 身份
-
-- 调用 `whoami`（可选）：确认 `role` / `openId`  
-- 调用 `get_my_quota`：看运行中数量是否达上限  
-
-### 1. 工程
-
-- 识别栈；保证 Dockerfile；`.gitignore` 排除密钥  
-- 有状态：默认 `/data`；多目录用 `persistence[]`  
-- 需要库：`databases: [{ engine: "postgres"|"mysql", ... }]`  
-- **若依赖 `@lark-apaas/*` / 妙搭模板：**  
-  - **先告知用户**：本平台不保证页面+接口可用；推荐 `lark-apps` 云端或业务去平台化  
-  - **禁止**主动承诺「自托管后与妙搭一致」  
-  - **禁止**在 skill 流程里大改登录/伪造网关/补 SPA 模板（那是业务仓责任，且非本 skill 范围）  
-  - 用户书面坚持后，仅按普通 Dockerfile 部署，交付时标注 **实验性**  
-- **Node 多阶段硬规则**（详见 `stack-profiles.md`）：  
-  - 禁止在 `npm ci`/`pnpm install` **之前** `ENV NODE_ENV=production`（否则 `nest`/`vite` not found）  
-  - 大前端 Vite：`NODE_OPTIONS=--max-old-space-size=3072`  
-  - runtime 用 `COPY --from=build` 串行，避免并行双 `npm ci` 把小机打爆
-
-### 2. 仓库与推送（权限红线）
+**前提：** §2 联通、§3 有有效 Key。工程为 **普通 Dockerfile** 服务（Python/Node/静态站等）。  
+妙搭/`@lark-apaas`：非主路径，见 `references/stack-profiles.md`；勿承诺与妙搭线上一致。
 
 ```text
-ensure_repository({ repo: "owner/name" 或 "name" })
-→ 使用返回的 agentHint.pushUrl（含企业机器人 Token）
-→ git add / commit
-→ git push --set-upstream "<pushUrl>" HEAD:<defaultBranch>
-→ 记录 commitSha
+┌─────────────────────────────────────────────────────────────┐
+│  A. 工程准备（本地）                                          │
+│  B. ensure_repository → pushUrl 推送（Agent，禁止用户 SSH）     │
+│  C. create_deployment_plan                                    │
+│  D. apply_deployment_plan   ← 卷/库/域名/构建全在这里          │
+│  E. 轮询 get_deployment_status / list_projects                 │
+│  F. 探活 URL → 按 §5 回复用户                                  │
+└─────────────────────────────────────────────────────────────┘
 ```
 
-**硬规则：**
+细节参数见 `references/mcp-deploy.md`；时序见 `references/sequence.md`。
 
-1. **禁止**要求用户上传/配置 `~/.ssh/id_ed25519.pub` 或任何个人 SSH Key。  
-2. **禁止**让用户自己去 Gitea 开权限、建仓、加 Collaborator。  
-3. **禁止**用未认证的 `cloneUrl` 去 `git push`（会 403 / Permission denied）。  
-4. **必须**用 `agentHint.pushUrl` 做一次推送；**不要**把 `pushUrl` 全文贴进对用户的回复。  
-5. 若仍 403：重新 `ensure_repository` 取新 hint，检查本机网络能否访问 `git.loncode.site`——**不要**改去配用户 SSH。
+### 4.1 工程准备（Agent）
 
-### 3. 计划与发布
+- [ ] 有 `Dockerfile`，进程监听 **`0.0.0.0` + 容器端口**（与 plan `spec.port` 一致）  
+- [ ] 有状态写 **`/data`**（或 `persistence[]` 声明的路径）  
+- [ ] `.gitignore` 排除 `.env`、密钥、本地 db  
+- [ ] 需要 PG/MySQL → plan 里 `databases: [{ "engine": "postgres", "envVar": "DATABASE_URL" }]`  
+- [ ] Node 大前端：见 `stack-profiles.md`（禁止 install 前 `NODE_ENV=production`；堆内存；串行 multi-stage）  
+
+### 4.2 仓库与推送
+
+```text
+ensure_repository({ repo: "项目名" 或 "Buxi/项目名" })
+→ 使用返回的 agentHint.pushUrl（内含企业机器人 Token）
+→ git add / commit
+→ git push --set-upstream "<pushUrl>" HEAD:<defaultBranch>
+→ 记录 commitSha（git rev-parse HEAD）
+```
+
+| 硬规则 | |
+|--------|--|
+| 必须用 `pushUrl` 推 | 不要用无 Token 的 `origin` |
+| 禁止要用户配 SSH / 加公钥到 Gitea | 失败则重取 `ensure_repository`，查网络 |
+| 禁止把 `pushUrl` 全文贴给用户 | |
+
+### 4.3 建计划
 
 ```text
 create_deployment_plan({
-  repo, commitSha, branch,
-  # environment = 控制面「部署标签」，默认 default。禁止擅自 invent production/staging
-  # 除非用户明确说「再部署一套并行环境」。与 status/redeploy 必须同一标签；不确定 list_projects
-  environment: "default",
+  repo,
+  commitSha,          # 已在 Gitea 上
+  branch: "main",
+  environment: "default",   # 除非用户明确要第二套并行环境
   spec: {
     buildType: "dockerfile",
     dockerfilePath: "Dockerfile",
     buildPath: "/",
     port: <容器端口>,
     healthcheckPath: "/",
-    persistence: [ /* 可选多卷；缺省自动加 /data */ ],
-    databases: [ /* 可选 postgres|mysql */ ],
     exposeWeb: true
+    # persistence / databases 按需
   }
 })
-→ apply_deployment_plan({ planId })
-→ 使用返回的 url / domain / databases（密码已脱敏）
+→ 记下 planId
 ```
 
-**环境概念（易混）：**
+**部署标签 `environment`：** 控制面 mapping 键，**不是** Dokploy 的 preview/production 分组。  
+默认 **`default`**。禁止因用户说「上线/生产」就改成 `production`。
 
-| 名称 | 是什么 | 谁决定 |
-|------|--------|--------|
-| Dokploy Environment | 应用建在平台哪个分组（如 preview） | 控制面 `DOKPLOY_ENVIRONMENT_ID`（全站统一） |
-| MCP `environment` | 部署标签，`repo+标签` 对应一套应用/域名 | Agent 参数，默认 `default`，全公司应统一 |
-
-已有项目若当初用了非 default 标签，重部署/查状态必须继续传该标签，不要擅自改（否则会当成新项目）。
-
-### 部署标签硬规则（Agent）
-
-1. **默认且优先**：省略 `environment` 或显式 `"default"`。  
-2. **禁止**仅因用户说「上线 / 生产 / 正式」就改成 `production`——那只是业务话术，不是部署标签。  
-3. **仅当**用户明确要求「第二套环境 / staging / 并行预发」时，才用非 default 标签。  
-4. 重部署前 `list_projects`，沿用已有 `environment` 字段。
-
-### 4. 轮询与交付
+### 4.4 发布
 
 ```text
-get_deployment_status / list_projects
-Web：curl -skI "$url" 或健康路径（证书可能短暂签发中）
+apply_deployment_plan({ planId })
 ```
 
-对用户：
+控制面内部（Agent **不要**再做）：挂卷 → 可选数据库 → 域名 `buxi`+5位+`DOMAIN_ROOT` + LE HTTPS → deploy。
 
-- 给 **HTTPS 链接**（`apply` 的 `url`）  
-- 不提 Gitea/Dokploy/Token  
-- 配额满、无权：原文转述 MCP 错误  
+从返回中取：`url` / `domain` / `applicationId` / `isNewProject`（**勿回显**数据库密码）。
 
-### 5. 域名与 HTTPS（控制面完成，Agent 勿重复 domain.create）
+### 4.5 轮询与探活
 
-- 默认 host：`buxi` + 5 位随机 `[a-z0-9]` + `.` + `DOMAIN_ROOT`  
-  例：`buxi3k9xa.loncode.site`  
-- 首次分配后 **固定**（存在控制面 mapping）  
-- HTTPS：Dokploy Traefik + **Let’s Encrypt 按子域签证书**（**不需要**通配符证书）  
-- DNS：建议 `*.loncode.site` → 服务器（通配 **解析**，不是通配证书）  
-- 证书失败：查 80/443、DNS；可暂 HTTP 仅当控制面 `DOMAIN_HTTPS=false`  
+```text
+每 15–30s：get_deployment_status({ repo, environment }) 或 list_projects
+终态：构建成功且运行中
+Web：curl -skI "$url"（证书首次可能 1–3 分钟）
+失败：get_sanitized_logs → 修代码/Dockerfile → 新 SHA → 新 plan → apply
+```
 
-Agent **不要**在 MCP 路径下再调 Dokploy `domain.create`（避免双绑/冲突）。
+同一 `repo`+`environment` 重部署：**复用**域名与卷，**不占**新配额名额。
 
-### 6. 卷与数据库
+### 4.6 工具速查
 
-| 能力 | 行为 |
+| 工具 | 何时 |
 |------|------|
-| 默认卷 | Docker named volume → `/data`（避免 bind 目录不存在导致 Swarm 0/1） |
-| bind 模式 | 可选；控制面 mkdir 宿主机路径，失败回退 volume |
-| 多卷 | `spec.persistence[]`；缺 `/data` 仍自动补 |
-| Postgres / MySQL | `spec.databases[]` → Dokploy 建库 + 注入 `DATABASE_URL` 等 |
-| 重部署 | 同 repo+env 不占新配额名额；域名与库记录复用 |
-
-应用必须把状态写在挂载路径（如 SQLite → `/data/app.db`）。
+| `whoami` | 联通 / 身份 |
+| `get_my_quota` | 部署前配额 |
+| `list_projects` | 我的项目、重部署标签 |
+| `inspect_project` | 单项目映射与策略 |
+| `ensure_repository` | 建库 + `pushUrl` |
+| `create_deployment_plan` | 已 push 的 SHA |
+| `apply_deployment_plan` | 真正发布 |
+| `get_deployment_status` | 轮询 |
+| `get_sanitized_logs` | 脱敏诊断 |
+| `reset_project_mapping` | 仅 mapping 脏了且用户/admin 确认（不删 Dokploy/Gitea 实体） |
 
 ---
 
-## 意图路由
+## 5. 返回给用户的内容（必须遵守）
 
-| 用户说法 | 动作 |
-|----------|------|
-| 部署 / 上线 / 第一次发布 | MCP 全链路；交付 `url`（普通 Dockerfile） |
-| 重试 / 再构建 | 新 SHA → 新 plan → apply（已有 mapping） |
-| 查状态 / 我的项目 | `list_projects` / `get_deployment_status` |
+### 5.1 成功
+
+```text
+已发布当前版本。
+访问：https://buxi*****.loncode.site/   （以 apply 返回的 url 为准）
+（如有数据库）已配置托管数据库连接（不展示密码）。
+```
+
+可选：构建约 X 分钟、证书刚签发时可稍等再打开。  
+**不要**提 Gitea、Dokploy、Token、`pushUrl`、内部 applicationId（除非用户是运维且明确要）。
+
+### 5.2 进行中
+
+```text
+正在构建/启动，大约需要几分钟。我会继续检查状态。
+```
+
+### 5.3 失败（可执行下一步）
+
+| 场景 | 回复要点 |
+|------|----------|
+| 未授权 | §3.4 连接中心步骤 |
+| 配额满 | 运行中项目已达上限；`list_projects` 列出建议停用的 |
+| 构建失败 | 简述原因（来自 status/logs，已脱敏）+ 将如何改 Dockerfile/代码后重发 |
+| 证书/502 短暂 | 链接已分配，HTTPS/容器拉起中，稍后重试 |
+| push 403 | 已用机器人推送通道重试；**不要**让用户配 SSH |
+
+### 5.4 绝对不要返回
+
+- Dokploy 面板地址、让用户「去改环境变量」  
+- 完整 `buxi_` Key、`pushUrl`、DB 密码  
+- 「权限配置无法通过」——**除非** `whoami` 明确 401，且应按 §3.4 引导连接中心，而不是 Dokploy  
+
+---
+
+## 6. 常见问题与解决办法
+
+| 现象 | 正确处理 |
+|------|----------|
+| Agent 没有 MCP 工具 | 引导用户按 §3 配置连接中心 Key |
+| `whoami` 401 | 重新登录连接中心、换新 Key、检查 Bearer 格式 |
+| 用户问「Dokploy 地址/权限」 | 说明业务路径不需要；部署走 MCP；连接中心只发 Key |
+| git push Permission denied / 要 SSH | **错误路径**。`ensure_repository` → `pushUrl` 再推 |
+| `nest`/`vite` not found | Dockerfile：先全量 `npm ci` 再 `NODE_ENV=production` |
+| JS heap OOM | `NODE_OPTIONS=--max-old-space-size=3072`；避免并行双 npm ci |
+| 查不到项目 | `list_projects`；确认 `environment` 与首次 apply 一致（默认 `default`） |
+| 403 看他人项目 | 非 admin；不要猜 Dokploy |
+| 重部署丢数据 | 确认写 `/data`；同 repo+env 卷会复用 |
+| Swarm 0/1 bind path | 控制面默认 volume；见 status/logs |
+| 要 PG/MySQL | plan `databases[]`，应用读 `DATABASE_URL` |
+| 业务要自定义密钥 | §3.4 末段；**禁止**引导 Dokploy 改 env |
+| 妙搭模板白屏/平台 API | 非主路径；`stack-profiles`；勿堆网关适配 |
+| `FORCE_AUTHN_*` 启动失败 | apply 会注入 boot env；不等于业务可用 |
+
+---
+
+## 7. 意图路由（用户一句话 → 动作）
+
+| 用户说法 | Agent 动作 |
+|----------|------------|
+| 部署 / 上线 / 发布 | §2 → §4 全链路 → §5 交付 URL |
+| 再发一版 / 重试 | push 新 SHA → create+apply（同 environment）→ 轮询 |
+| 我的项目 / 链接 | `list_projects` / `get_deployment_status` |
 | 配额 | `get_my_quota` |
-| 只要链接 | `list_projects` 看 `url`；无则查 status |
-| 运维直连 Dokploy | 仅明确要求时走 legacy |
-| 妙搭应用 / `@lark-apaas` 上线 | **先边界说明**；优先 `lark-apps`；自托管仅实验、不承诺接口 |
-| 修妙搭白屏 / 平台 API / 登录伪造 | **非本 skill**；说明需业务去平台化或妙搭云端，勿在控制面堆适配 |
+| 连不上 / 没权限 | **只**走 §2–§3（连接中心），**禁止** Dokploy |
+| 运维直连 Dokploy | 仅用户**明确**要求且本机有 `.env.deploy` → §8 |
+| 妙搭应用 | 先边界说明；优先 `lark-apps`；自托管实验见 stack-profiles |
 
 ---
 
-## 对用户话术
+## 8. Legacy：直连 Dokploy（运维例外 · 默认关闭）
 
-**成功：**
+**仅当**同时满足：
 
-- 已发布当前版本  
-- 访问：`https://buxi….loncode.site/`（以 MCP 返回为准）  
-- 需要库时：说明已注入数据库连接（**不打印密码**）  
-- 若为妙搭实验部署：明确 **「仅容器/入口可能可用，登录与平台接口不保证」**  
+1. 用户明确说「不要 MCP / 运维直连 Dokploy」；且  
+2. 本机有 `.env.deploy` + `DEPLOY_AUTHORIZED=true`  
 
-**失败：**
+才可直连 Dokploy API。模板见 `references/env-deploy.example`。  
 
-- 配额满 / 未登录 Key / 构建失败 / 证书签发中  
-- 给可执行下一步，不暴露平台密钥  
-
-**拒绝加戏：**
-
-- 不要为了「页面像妙搭」去改 skill 流程、伪造网关、承诺 runtime API  
-- 控制面 `SELF_HOST_*` 只是 boot 兜底，不是功能完整度保证  
+**有 MCP 时禁止向业务要 `DOKPLOY_API_KEY`。**  
+默认对话 **不要** 提 Dokploy 面板。
 
 ---
 
-## 安全红线
+## 9. 支持范围（产品收口）
 
-1. 永不 commit / 回显：`buxi_` Key、`MCP_AUTH_TOKEN`、Dokploy/Gitea Token、`pushUrl`、数据库密码全文  
-2. `apply` 返回的 `connectionUrl` 已脱敏则保持；未脱敏则遮罩  
-3. 普通用户不可查他人项目（控制面会 403）  
-4. 生产破坏性操作仍受控制面策略约束  
-5. **禁止**因 push 失败引导用户配置个人 SSH（那是错误路径）
+| 栈 | 状态 |
+|----|------|
+| 普通 Python / Node / 静态站 + Dockerfile | **支持**（主路径） |
+| 自管登录与 DB 的 API | **支持** |
+| 飞书妙搭 / `@lark-apaas/*` | **实验性**；不承诺登录/平台 API；见 `stack-profiles.md` |
+
+主路径承诺：Dockerfile + 端口 + `/data` + 可选库 → **HTTPS 链接**。  
+不承诺：模拟妙搭网关、业务自定义 env 面板、用户进入 Dokploy。
 
 ---
 
-## Agent 检查清单（MCP）
+## 10. 参考文件
 
-- [ ] MCP 可用；`whoami` 正常  
-- [ ] Dockerfile + 数据写挂载点  
-- [ ] `ensure_repository` + push + `commitSha`  
-- [ ] plan 含正确 `port`；需要时 `persistence` / `databases`  
-- [ ] `apply` 拿到 `url`  
-- [ ] 轮询至终态；探活  
-- [ ] 未向用户索要 Dokploy/Gitea 地址或 Token  
-
----
-
-## Legacy：直连 Dokploy（运维例外）
-
-**仅当**用户明确要求或 MCP 不可用且有 `.env.deploy`：
-
-1. `set -a && source .env.deploy && set +a`，`DEPLOY_AUTHORIZED=true`  
-2. 按旧流程：Dockerfile → push → `application.*` / `mounts` / `domain.create` / deploy  
-3. 域名规则见 `references/domain.md` **Legacy** 段（与 MCP 的 `buxi+5` 规则不同，勿混用）  
-4. 模板：`references/env-deploy.example`  
-5. 仍禁止把密钥贴进聊天  
-
-**默认对话不要走这条。** 有 MCP 时禁止向业务索要 `DOKPLOY_API_KEY`。
-
----
-
-## 与其它 skill 边界
-
-| 场景 | 用 |
-|------|-----|
-| 企业 Dockerfile 部署（默认） | **本 skill → MCP** |
-| 妙搭云端发布 / 平台能力迭代 | **`lark-apps`**（首选） |
-| 妙搭模板硬上自托管 | 非主路径；见 `stack-profiles`；**不**在本 skill 做深度适配 |
-| 无 MCP 的运维救火 | 本 skill → legacy |
-
----
-
-## 故障速查（MCP）
-
-| 现象 | 处理 |
+| 文件 | 内容 |
 |------|------|
-| 401 / 要 Feishu Key | 引导连接中心登录，配置 `buxi_` |
-| git push 权限 / Permission denied / 要配 SSH | **错误路径**。改用 `ensure_repository` → `agentHint.pushUrl` 推送；禁止给用户配 SSH |
-| `nest: not found` / `vite: not found` | build 阶段在装依赖前设了 `NODE_ENV=production`；先全量 `npm ci` 再设 production |
-| `JavaScript heap out of memory` | Dockerfile build 加 `NODE_OPTIONS=--max-old-space-size=3072`；避免并行 npm ci；机器内存过小则升配 |
-| `FORCE_AUTHN_INNERAPI_DOMAIN` / 平台模式需要基础域名 | 镜像仍带 PlatformModule 时缺 boot env；`apply` 会注入公网 URL；**不表示业务已可用** |
-| 妙搭项目：页面白屏 / `{{appId}}` / 接口 403·404 / JSON 解析 HTML | **预期内能力缺口**（非本 skill 必修）。引导去平台化或 `lark-apps`；勿在控制面加网关适配 |
-| 运行中项目达上限 | `get_my_quota`；停/删旧应用后再部署 |
-| Forbidden 看他人项目 | 非管理员；加 `ADMIN_OPEN_IDS` 或只查自己的 |
-| 有部署无 HTTPS | 等 LE；查 DNS/80；控制面证书配置 |
-| 重部署丢数据 | 确认写 `/data`；控制面默认挂载是否开启 |
-| Swarm 0/1 + bind path does not exist | 控制面已默认 volume + mkdir；旧应用可 `mkdir -p` 宿主机路径或删 bind 改 volume 后 redeploy |
-| 要 PG/MySQL | plan 里带 `databases`，勿手建后不注入 env |
+| `references/mcp-deploy.md` | 工具参数、JSON 示例、apply 内部顺序 |
+| `references/sequence.md` | 时序图 |
+| `references/domain.md` | 域名与 HTTPS |
+| `references/stack-profiles.md` | Dockerfile 约定 + 支持矩阵 |
+| `references/env-deploy.example` | 仅 legacy |
+
+线上：
+
+- 连接中心：https://company-deploy-mcp.loncode.site/  
+- MCP：https://company-deploy-mcp.loncode.site/mcp  
+- 技能仓：http://git.loncode.site/Buxi/company-deploy-skills  
+
+---
+
+## 11. Agent 出发前检查清单
+
+- [ ] 已 `whoami` 成功（不是假设有权限）  
+- [ ] 未要求用户打开 Dokploy / 提供面板账号  
+- [ ] 未索要 `DOKPLOY_API_KEY` / 用户 SSH  
+- [ ] Dockerfile + port + `/data`（及可选 databases）  
+- [ ] `ensure_repository` + **pushUrl** 推送 + `commitSha`  
+- [ ] `environment` 默认 `default` 或与历史一致  
+- [ ] `apply` 后轮询并交付 **HTTPS url**  
+- [ ] 回复符合 §5（无密钥、无 Dokploy 推诿）