refactor(plugin)!: 插件改名 studio、新增 writer、统一本机 stdio 管道

命名结构（品牌=市场，产品=插件）：市场名保持 deta；插件 deta → studio（displayName DETA Studio），新增 writer（DETA Writer）。安装标识 studio@deta / writer@deta；MCP 服务名 studio_mcp / writer_mcp，可同时安装。plugins/deta → plugins/studio（git mv 保留历史），新增 plugins/writer。

连接形态统一为单一本机 stdio 管道：.mcp.json 与 cordis.patch.yml 均声明 stdio → bin/deta-mcp.sh --profile <产品>，并按官方插件写法补 cwd: "."（缺它时 Cwd=- ，相对命令按宿主进程 cwd 解析会静默起不来）；启动器新增 --profile 档位（工作区 ~/.deta/<产品>/workspace、工具面缺省 full），运行时按 DETA_SERVER_ROOT → ~/.deta/runtime → 开发检出解析，入口优先打包产物；DETA_TOKEN 可选注入（缺省时云类工具返回 auth_required）。原远程端点声明（含 OAuth/401 段落）从插件移除。

文档与治理：根 README 与两个插件 README 改为单一管道口径；技能 aml-design 对齐本机全量面；新增 scripts/check-plugin-contract.mjs（E1 禁工具清单 / E2 必须给出 list_capabilities / E3 禁解释内部实现 / E4 市场条目一致性 / W1 开发检出依赖）与 .gitea/workflows/ci.yml。版本：studio 0.3.1、writer 0.1.0。

README.md

@@ -1,15 +1,70 @@
 # DETA — Agent Plugins
 
-DETA 领域能力在各类 Agent harness 上的分发仓：**一份产物，多个宿主壳**。
+DETA 领域能力在各类 Agent harness 上的分发仓：**品牌 = 市场，产品 = 插件，一个仓承载多产品**。
 
 | 宿主 | 形态 | 安装 |
 |------|------|------|
-| Codex | 插件（`.codex-plugin/plugin.json` + `skills/` + `.mcp.json`）；本仓同时是 Codex 插件市场 | `codex plugin marketplace add https://git.deta.city/deta/deta-agent-plugins.git` → `codex plugin add deta@deta` |
-| dsh (deepseek-harness) | 组合包 bundle（`dsh.bundle.patch` + `cordis.patch.yml`） | `dsh plugin --profile <name> add ./plugins/deta` |
+| Codex | 插件（`.codex-plugin/plugin.json` + `skills/` + `.mcp.json`）；本仓同时是 Codex 插件市场 `deta` | `codex plugin marketplace add https://git.deta.city/deta/deta-agent-plugins.git` → `codex plugin add studio@deta` |
+| dsh (deepseek-harness) | 组合包 bundle（`dsh.bundle.patch` + `cordis.patch.yml`） | `dsh plugin --profile <name> add ./plugins/studio` |
 
-能力本体（AML 建筑模型读写、编译校验、围护结构统计、空间邻接查询）以 MCP 服务提供，
-同一份后端与技能被所有宿主复用；新增宿主只需再加一层声明式壳。
+发行标识（Codex 语法 = 插件@市场）：**`studio@deta`**、**`writer@deta`**——两个插件互不冲突，
+可同时安装（MCP 服务名 `studio_mcp` / `writer_mcp`，工作区各自独立）。新增产品按同一结构落位：
+`plugins/<产品>/` 自带 `.codex-plugin/plugin.json`、`.mcp.json`、`package.json`、`cordis.patch.yml`、
+`bin/`、`skills/`、`README.md`，市场 `plugins` 数组加一条即可。
 
+能力本体（AML 建筑模型读写、编译校验、围护结构统计、空间邻接查询）以 **MCP 服务**提供，
+运行时在**本机**解析（引擎包 / 源码构建），宿主侧只声明"用哪个启动器"；
+同一份后端、同一个启动器、同一套技能被所有宿主复用，新增宿主只需再加一层声明式壳。
+
+## 职责边界（仓库章程）
+
+本仓是**宿主适配与分发层，零逻辑、不承载契约**。三条铁律：
+
+| 问题 | 归属 | 内容 |
+|------|------|------|
+| 能力在哪 | **ant-copilot**（唯一来源） | 工具实现、MCP 协议层、启动形态（本机 stdio / 服务端 HTTP）、工具面裁剪、领域技能 |
+| 怎么被发现和启动 | **本仓** | 宿主清单（`.codex-plugin/plugin.json`、`cordis.patch.yml`）、连接声明（`.mcp.json`）、启动器、宿主侧技能投影 |
+| 怎么在云上跑 | **infra** | 部署 / 证书 / 路由 / 重启；云端只跑 ant-copilot 的构建产物 |
+
+因此本仓**不做**这些事（由 `scripts/check-plugin-contract.mjs` 在 CI 强制）：
+
+- 不在文档或技能里列**工具清单 / 工具一览**——工具面按部署形态裁剪，清单必然过期；
+  取清单的唯一途径是运行时调用 `list_capabilities`（技能必须给出这条指引）。
+- 不解释 ant-copilot 的内部常量与实现路径（`DETA_TOOL_SURFACE`、`dist/…` 等）。
+- 不把「开发检出路径」当作运行前提——启动器应随包解析运行时（当前仍保留开发检出回落，
+  校验脚本以 warning 提示，本机引擎包落地后升级为 error）。
+- 市场条目与实际插件目录**必须一致**（条目 `name` = 插件清单 `name`、`path` 真实存在），
+  由校验脚本的 E4 规则强制——改名或加产品时不会留下悬空条目。
+
+**衡量标准**：新增一个工具需要改几处？目标是 **1 处**（ant-copilot 注册工具，
+能力目录与文档自动派生），本仓零改动。
+
+## 连接形态（唯一管道：本机 stdio）
+
+```
+宿主（Codex / dsh）
+  └─ 拉起 plugins/<产品>/bin/deta-mcp.sh --profile <产品>    ← 各产品带自己的档位，脚本同一份
+        ├─ 解析领域服务运行时：DETA_SERVER_ROOT → ~/.deta/runtime → 本机开发检出
+        ├─ 解析工作目录：DETA_WORKSPACE → ANT_HEADLESS_WORKSPACE → ~/.deta/<产品>/workspace
+        └─ 执行领域服务运行时入口（打包产物；回落未打包产物时打印警告）
+             └─ MCP stdio：全量工具面；无 OAuth、无 401、无令牌续期
+```
+
+- **本机形态不做 MCP 鉴权**：进程在本机由宿主或用户拉起，天然可信。
+- 云侧能力（项目/楼栋列表、同步）是**可选的输入**：注入 `DETA_TOKEN` 即有，缺省时云类工具
+  返回 `auth_required`，其余工具照常——同一份工具实现，不是两套分支。
+- Studio 执行器中继（模拟/画布）需 `ANT_WORKSPACE_BRIDGE_URL` + 项目 ID 三要素齐备。
+- **各产品独立命名空间**：MCP 服务名 `studio_mcp` / `writer_mcp`（工具前缀
+  `mcp__<服务名>__<工具>`），两个插件可同时安装互不冲突；产品间不共享工作区。
+- 服务端仍保留 HTTP 形态的服务（数据面/其他客户端用），但它**不是本插件声明的连接形态**；
+  插件的连接声明只有本机 stdio 一种。
+
+## 内容
+
+| 插件 | 服务名 | 技能 | 能力 | 依赖 |
+|------|--------|------|------|------|
+| `studio@deta` | `studio_mcp` | `studio:aml-design` | AML 建筑模型读写、编译与校验、围护结构统计、空间邻接查询 | node；领域服务运行时（本机引擎包或源码构建） |
+| `writer@deta` | `writer_mcp` | `writer:report-authoring` | 报告/文档产出：读模型、取数据（统计/分析/模拟缓存/气象/规范）、成文 | 同上 |
 
 ## 安装（Codex）
 
@@ -18,75 +73,30 @@ DETA 领域能力在各类 Agent harness 上的分发仓：**一份产物，多
 codex plugin marketplace add https://git.deta.city/deta/deta-agent-plugins.git
 
 codex plugin list
-codex plugin add deta@deta
+codex plugin add studio@deta
 
-# 登录（一次性）：打开浏览器完成 deta.city 账号登录
-codex mcp login deta_mcp
+# 准备领域服务运行时（二选一）：本机引擎包（~/.deta/runtime）或源码构建
+#   源码构建：在领域服务仓库执行 npm run build:mcp
+# 冒烟（应等待 stdin/stdout）
+bash plugins/studio/bin/deta-mcp.sh
 ```
 
-`codex mcp login deta_mcp` 走 OAuth 2.1（授权码 + PKCE S256 + 动态客户端注册）：终端给出
-`https://deta.city/oauth/authorize?...`，在浏览器里用 deta.city 账号登录并授权即可，
-随后 Codex 自行保管令牌并按 refresh token 自动续期。退出登录用 `codex mcp logout deta_mcp`。
-
-不支持 OAuth 的宿主（dsh / 脚本 / CI）改用登录助手换取 `DETA_TOKEN`：
+装完即用，**没有 OAuth 登录步骤**。需要云侧能力时注入令牌（助手见
+`plugins/studio/README.md`「登录助手」）：
 
 ```bash
-node ~/Dev/ant/deta-agent-plugins/plugins/deta/bin/deta-login.mjs
-source ~/.deta/env        # 让 DETA_TOKEN 进入当前 shell 环境
+node plugins/studio/bin/deta-login.mjs
+source ~/.deta/env        # 让 DETA_TOKEN 进入宿主进程环境
 ```
 
-未登录时 MCP 端点返回 **401**，并带 OAuth 发现提示头
-（`WWW-Authenticate: Bearer resource_metadata="https://deta.city/.well-known/oauth-protected-resource/mcp-api/mcp"`）——
-标准 MCP 客户端据此自动进入浏览器授权流程，含义是「当前环境没有可用的 deta.city 登录态」。
-
-## 内容
-
-| 插件 | 技能 | 能力 | 依赖 |
-|------|------|------|------|
-| `deta` | `deta:aml-design` | AML 建筑模型读写、编译与校验、围护结构统计、空间邻接查询 | node；领域服务已构建 |
-
-## 前置条件
-
-| 项 | 值 |
-|----|-----|
-| MCP 端点 | `https://deta.city/mcp-api/mcp`（MCP Streamable HTTP） |
-| 凭据来源 | **deta.city 账号**；`bin/deta-login.mjs` 登录取令牌，经环境变量 `DETA_TOKEN` 传给 harness |
-| 凭据文件 | `~/.deta/credentials.json`（令牌 + 账号 + 端点）、`~/.deta/env`（`export DETA_TOKEN=...`），均 0600 |
-
-端点除探活接口（服务端 `GET /health`，经 Nginx 前缀对外为 `/mcp-api/health`）外全部需要鉴权：
-
-- 未带凭据 / 凭据失效 → `401`（提示重新登录，不回显凭据）；
-- 服务端认证服务不可用 → `500`，同样不放行；
-- 各账号在服务端有独立工作区（`<工作区根>/<账号 ID>`），互不可见。
-
-### 本地 stdio 形态（开发用，默认关闭）
-
-本机开发时也可以直连领域服务的无头 MCP 服务（`bin/deta-mcp.sh`，stdio），
-它**不校验 deta.city 账号、不隔离工作区**，仅供本机迭代领域能力：
-
-```bash
-cd ~/Dev/ant/ant-copilot && npm run build
-node dist/src/headless/mcp-server.js   # 冒烟：应等待 stdin/stdout
-```
-
-该形态的环境变量：
-
-| 变量 | 缺省 | 说明 |
-|------|------|------|
-| `DETA_SERVER_ROOT` | `~/Dev/ant/ant-copilot` | 领域服务仓库根目录（内部路径） |
-| `ANT_HEADLESS_WORKSPACE` | `<cwd>/workspace` | AML 工作目录（`aml.xml` / `building.json` 落盘处，名称由底层服务决定） |
-
-编译与校验类工具需要**编译服务**在线（服务端地址由底层环境变量 `DETA_GSA_URL` 给出，缺省
-`localhost:8000`）；未在线时返回明确错误，读写类工具可离线工作。
-
 ## 本地迭代
 
 插件内容改动后 Codex 不会自动感知，按官方流程打 cachebuster 版本号再重装：
 
 ```bash
 python3.11 ~/.codex/skills/.system/plugin-creator/scripts/update_plugin_cachebuster.py \
-  ~/Dev/ant/deta-agent-plugins/plugins/deta
-codex plugin add deta@deta
+  ~/Dev/ant/deta-agent-plugins/plugins/studio
+codex plugin add studio@deta
 ```
 
 （版本号形如 `0.1.0+codex.20260910020424`；重装后需开新会话才能加载新技能。）
@@ -95,105 +105,91 @@ codex plugin add deta@deta
 
 ```bash
 python3.11 ~/.codex/skills/.system/plugin-creator/scripts/validate_plugin.py \
-  ~/Dev/ant/deta-agent-plugins/plugins/deta
+  ~/Dev/ant/deta-agent-plugins/plugins/studio
+node scripts/check-plugin-contract.mjs          # 本仓章程校验（CI 同款）
 codex plugin marketplace list
-codex mcp list | grep deta
+codex mcp list | grep -i studio                 # 应显示 stdio 形态（Command 列）与 studio_mcp
 ```
 
 ## 双壳架构（Codex + dsh 同一产物）
 
-`plugins/deta/` 这一个目录同时是 Codex 插件根与 dsh 组合包根，共享核心、各带一层薄壳：
+`plugins/studio/` 这一个目录同时是 Codex 插件根与 dsh 组合包根，共享核心、各带一层薄壳：
 
 | 组成 | 文件 | Codex | dsh |
 |------|------|-------|-----|
-| 插件清单 | `.codex-plugin/plugin.json` | ✅ 使用 | — |
-| MCP 声明 | `.mcp.json` | ✅ 使用（可放 Codex 私有键） | — |
+| 插件清单 | `.codex-plugin/plugin.json`（`name` = 产品名） | ✅ 使用 | — |
+| MCP 声明 | `.mcp.json`（stdio → `bin/deta-mcp.sh --profile <产品>`，`serverName` = `<产品>_mcp`） | ✅ 使用（可放 Codex 私有键） | — |
 | 组合包声明 | `package.json`（`dsh.bundle.patch`） | 忽略 | ✅ 使用 |
-| 配置层 | `cordis.patch.yml` | 忽略 | ✅ 使用 |
-| 领域技能 | `skills/aml-design/SKILL.md` | ✅ 共享 | ✅ 共享 |
-| 本地启动器 | `bin/deta-mcp.sh` | ✅ | 由配置层的 `args` 直接指向服务入口 |
+| 配置层 | `cordis.patch.yml`（同一启动器，stdio，`serverName` = `<产品>_mcp`） | 忽略 | ✅ 使用 |
+| 宿主侧技能 | `skills/aml-design/SKILL.md` | ✅ 共享 | ✅ 共享 |
+| 启动器 | `bin/deta-mcp.sh` | ✅ 每产品一份（同一实现，产品差异走 `--profile`） | ✅ |
 
 共享面（两端一致，零适配）：
 - **技能文件格式**：`<name>/SKILL.md` + frontmatter 必填 `name`/`description`，kebab-case。
   Codex 与 dsh（`@deepseek-ai/dsh-skill-filesystem`）要求相同。
 - **共享技能根**：两端都扫描 `~/.agents/skills/` 与 `<项目>/.agents/skills/`
   （dsh 侧为 rank 500 / 200 的发现根，且显式支持 `<agentsHome>/skills`）。
-  把技能放这里即可双端生效，不需要安装插件。
-- **MCP 工具命名**：两端同为 `mcp__<serverName>__<tool>`，我们统一 `serverName = deta`，
-  因此技能里写裸工具名（`read_source`、`apply_design`）在两端都能解析。
+- **MCP 工具命名**：两端同为 `mcp__<serverName>__<tool>`，我们统一 `serverName = deta`。
 
 各自不同的部分（不共享）：
-- MCP 的声明位置不同（Codex 读 `.mcp.json`，dsh 读 `cordis.patch.yml` 的 mcp-client 行）。
-- Codex 私有键（`default_tools_approval_mode`、`supports_parallel_tool_calls`）只写在
-  `.mcp.json`，不影响 dsh；dsh 无审批模式概念。
-- 分发渠道不同：Codex 走 git 市场，dsh 走 npm / git / tarball，且 dsh 没有官方市场。
+- MCP 的声明位置不同（Codex 读 `.mcp.json`，dsh 读 `cordis.patch.yml` 的 mcp-client 行），
+  但**都指向同一个启动器**。
+- Codex 私有键（`default_tools_approval_mode`、`omit_tools_from`）只写在 `.mcp.json`。
+- 分发渠道不同：Codex 走 git 市场，dsh 走 npm / git / tarball。
 
 ### dsh 侧安装与验证
 
 ```bash
-# 安装进某个 profile（pnpm 转发）
-dsh plugin --profile <name> add ~/Dev/ant/deta-agent-plugins/plugins/deta
-
-# 公开发布形态（二选一）
-npm publish                       # 用户：dsh plugin --profile <name> add deta-plugin
-dsh plugin --profile <name> add github:<你>/<仓库>   # 需作者提供 prepare + 用户 allowBuilds
+export DETA_PLUGIN_ROOT=~/Dev/ant/deta-agent-plugins/plugins/studio
+dsh plugin --profile <name> add "$DETA_PLUGIN_ROOT"
 
 # 只验证配置层是否合并正确（不启动、不需凭据）
 cd ~/Dev/ant/deepseek-harness
 node apps/cli/lib/bin.js --profile headless --dump-config \
-  --patch ~/Dev/ant/deta-agent-plugins/plugins/deta/cordis.patch.yml
-# 输出中应出现 `# == .../plugins/deta/cordis.patch.yml` 与 deta-mcp 行
+  --patch "$DETA_PLUGIN_ROOT/cordis.patch.yml"
+# 输出中应出现 `# == .../plugins/studio/cordis.patch.yml` 与 deta-mcp（transport: stdio）
 ```
 
-`cordis.patch.yml` 当前默认启用**远程端点**（`streamable-http` +
-`Authorization: Bearer ${DETA_TOKEN}`，指向 `https://deta.city/mcp-api/mcp`）；
-本地 stdio 段保留为注释、标注「本机开发用，默认关闭」，需要时手工切换。
+## 已知缺陷（实测）
 
-## 已知缺陷（实测，2026-09-10）
-
-**上游：编码代理 × 模型服务 命名空间重复**
-
-会话累积较多本插件工具调用后，代理会在请求里重复声明 MCP 命名空间，模型服务的
-Responses 兼容层拒绝请求：
-
-```
-Duplicate namespace name 'deta'; Namespace names must be unique.
-```
-
-复现记录（同一插件、不同会话长度）：
-
-| 代理版本 | 会话规模 | 触发位置 |
-|---------|---------|---------|
-| 0.144.4 | 一步并发 2 次调用 | input[10]、input[18] |
-| 0.144.4 | 串行 7–8 次调用 | input[37]、input[47] |
-| 0.154.0 | 短会话 5 工具 | 未触发 |
-| 0.154.0 | 长会话（≈15+ 工具） | input[260] |
-
-已排除/无效的手段：`wire_api = "chat"`（该版本已移除，仅支持 responses）、
-`features.non_prefixed_mcp_tool_names`（仅去掉命名空间前缀，重复依旧）、
-`supports_parallel_tool_calls = false`（削弱并发触发面，长会话仍复现）。
-
-**应对**：完成一个任务后另起会话；撞到该错误不要重试，重开会话即可（工作区文件保留）。
+**上游：编码代理 × 模型服务 命名空间重复** —— 会话累积较多本插件工具调用后，代理会在请求里
+重复声明 MCP 命名空间，模型服务的 Responses 兼容层拒绝并报
+`Duplicate namespace name 'deta'; Namespace names must be unique.`。
+应对：完成一个任务后另起会话；撞到该错误不要重试（工作区文件保留）。
+复现记录与已排除手段见 `plugins/studio/README.md`。
 
 ## 已修缺陷（实测）
 
 | 现象 | 根因 | 修复 |
 |------|------|------|
-| 写类工具返回 `user cancelled MCP tool call` | MCP 工具默认需审批，非交互模式下无法弹窗 | `.mcp.json` 加 `default_tools_approval_mode: "approve"`（实测 `auto`/`writes` 都会被取消，只有 `approve` 放行） |
-| 并发调用触发命名空间重复 | 代理并发序列化 | `.mcp.json` 加 `supports_parallel_tool_calls: false` |
+| 写类工具返回 `user cancelled MCP tool call` | MCP 工具默认需审批，非交互模式无法弹窗 | `.mcp.json` 声明 `default_tools_approval_mode: "approve"` |
+| 本机 stdio 形态起不来：`ERR_UNSUPPORTED_DIR_IMPORT` | 启动器指向未打包的产物（依赖包目录 import 在 Node ESM 下非法） | 领域服务提供打包入口；启动器优先取打包产物，回落未打包产物时打印警告 |
+| 一个插件两种形态并存（远程 URL + 本机 stdio） | 历史遗留，语义冲突 | 统一为本机 stdio 单一管道 |
+| 启动器把开发检出当唯一运行前提 | 默认值写死开发检出路径 | 运行时按 `DETA_SERVER_ROOT → ~/.deta/runtime → 开发检出` 解析，回落时打印提示 |
 
 ## 目录结构
 
 ```
 .agents/plugins/marketplace.json        # Codex 默认市场（ChatGPT 登录用户）
 .agents/plugins/api_marketplace.json    # Codex API key 登录用户市场
-plugins/deta/                           # 同一目录 = Codex 插件根 = dsh 组合包根
-├── .codex-plugin/plugin.json           # Codex 插件清单
-├── .mcp.json                           # Codex MCP 声明（远程 streamable-http）
+.gitea/workflows/ci.yml                 # CI：跑 scripts/check-plugin-contract.mjs
+scripts/check-plugin-contract.mjs       # 仓库章程校验（工具清单 / 内部实现 / 开发检出依赖）
+plugins/studio/                          # 产品插件：同一目录 = Codex 插件根 = dsh 组合包根
+├── .codex-plugin/plugin.json           # Codex 插件清单（name: studio）
+├── .mcp.json                           # Codex MCP 声明（studio_mcp → ./bin/deta-mcp.sh --profile studio）
 ├── package.json                        # dsh 组合包声明（dsh.bundle.patch）
-├── cordis.patch.yml                    # dsh 配置层（挂载 MCP 服务）
+├── cordis.patch.yml                    # dsh 配置层（同一启动器，serverName: studio_mcp）
 ├── bin/deta-login.mjs                  # 登录助手（~/.deta/credentials.json + ~/.deta/env）
-├── bin/deta-mcp.sh                     # 本地 stdio 启动器（开发用，默认关闭）
-├── README.md                           # 插件说明（安装/凭据/401 语义）
-└── skills/aml-design/SKILL.md          # 领域技能（两宿主共享）
+├── bin/deta-mcp.sh                     # 本机 stdio 启动器（多产品共用；--profile 区分档位）
+├── README.md                           # 插件说明（连接形态 / 凭据 / 排障）
+└── skills/aml-design/SKILL.md          # 宿主侧技能（不含工具清单）
+plugins/writer/                          # 产品插件：报告/文档产出
+├── .codex-plugin/plugin.json           # Codex 插件清单（name: writer）
+├── .mcp.json                           # Codex MCP 声明（writer_mcp → ./bin/deta-mcp.sh --profile writer）
+├── package.json                        # dsh 组合包声明（dsh.bundle.patch）
+├── cordis.patch.yml                    # dsh 配置层（同一启动器，serverName: writer_mcp）
+├── bin/deta-login.mjs                  # 登录助手（云侧能力用）
+├── bin/deta-mcp.sh                     # 本机 stdio 启动器（同一实现；缺省档位 writer）
+├── README.md                           # 插件说明（连接形态 / 能力边界 / 排障）
+└── skills/report-authoring/SKILL.md    # 宿主侧技能（报告取数与纪律）
 ```