ringo
c77d2fe864
CI / contract (push) Has been cancelled
配合 ant-copilot 新增的 login 工具（回环 OAuth 授权）：技能里 auth_required 的处置从"让用户去终端跑命令"改为"调 login 工具 + 浏览器点一下允许"；三份 README 同步，终端助手降为无 login 工具形态（CLI 等）的兜底。
88 lines
5.2 KiB
Markdown
88 lines
5.2 KiB
Markdown
# DETA Writer 插件（Codex 插件 / dsh 组合包）
|
||
|
||
DETA 领域能力在**报告产出**档位上的分发壳：同一个目录既是 Codex 插件根，
|
||
也是 dsh 组合包根，两端共享 `skills/` 与**同一个启动器**（与 Studio 插件共用实现）。
|
||
|
||
- 发行标识：**`writer@deta`**（插件 `writer` + 市场 `deta`）
|
||
- MCP 服务名：**`writer_mcp`**（工具前缀 `mcp__writer_mcp__…`；与 `studio_mcp` 互不冲突，可同时安装）
|
||
- 产品档位：启动器 `--profile writer`（工作区缺省 `~/.deta/writer/workspace`，与 Studio 隔离）
|
||
|
||
## 连接形态与凭据（唯一管道：本机 stdio）
|
||
|
||
| 项 | 值 |
|
||
|----|-----|
|
||
| 形态 | **本机 stdio**：宿主拉起 `bin/deta-mcp.sh --profile writer`，由它解析领域服务运行时与工作目录 |
|
||
| 宿主声明 | Codex 读 `.mcp.json`；dsh 读 `cordis.patch.yml`——两边都只声明"调用同一个脚本、带哪个档位" |
|
||
| 工作目录 | `DETA_WORKSPACE` → `ANT_HEADLESS_WORKSPACE` → 缺省 `~/.deta/writer/workspace`（启动器创建并在 stderr 回显） |
|
||
| 运行时 | `DETA_SERVER_ROOT` → `~/.deta/runtime` → 本机开发检出（回落到开发检出时启动器打印提示） |
|
||
| 云侧能力（可选） | `DETA_TOKEN`（`node bin/deta-login.mjs` 获取）：项目/楼栋列表、`push_project` / `pull_project` |
|
||
| Studio 执行器中继（可选） | `ANT_WORKSPACE_BRIDGE_URL` + 项目 ID（三要素齐备才启用；供模拟/画布类工具） |
|
||
|
||
**本机形态不做 MCP 鉴权**（进程由宿主或用户在本机拉起，没有 OAuth、没有 401、没有令牌续期）。
|
||
未注入 `DETA_TOKEN` 时，云类工具返回 `auth_required`，其余工具照常。
|
||
|
||
## 能力现状与边界（重要）
|
||
|
||
| 能力 | 现在由谁承担 |
|
||
|------|--------------|
|
||
| 读模型与工作区（`aml.xml` / `building.json`） | 宿主原生文件工具 + MCP 工作区工具 |
|
||
| 取数：围护结构统计、性能分析、模拟缓存、气象、规范指标 | MCP 引擎工具（与 `studio_mcp` 同一实现） |
|
||
| 报告成文（章节文本、结论、缺项标注） | 本项目技能 `report-authoring` 指导下的写作过程，产物落工作区 |
|
||
| **报告模板、插槽填充、docx 导出** | **门户 Writer 页面**（`https://deta.city/writer?doc=<docId>`）——**不是 MCP 工具** |
|
||
|
||
即：本插件当前复用与 Studio 相同的引擎工具面（报告类工具尚无 MCP 出口），
|
||
差异体现在**产品档位（独立工作区、独立命名空间）与写作技能**上。专用报告工具面
|
||
（插槽词表 / 报告文档读写）属引擎侧待补项，落地后本插件只需把档位的工具面切过去。
|
||
|
||
## 工具面约定
|
||
|
||
- 本机形态为全量工具面。**当前可用的完整工具名以运行时 `list_capabilities` 为准**，
|
||
本仓文档不列举工具清单。
|
||
- 写类工具在 Codex 侧需要审批：`.mcp.json` 已声明 `default_tools_approval_mode: "approve"`。
|
||
|
||
## 安装（Codex）
|
||
|
||
```bash
|
||
codex plugin marketplace add https://git.deta.city/deta/deta-agent-plugins.git
|
||
codex plugin add writer@deta
|
||
|
||
# 领域服务运行时：本机引擎包（~/.deta/runtime）或源码构建；冒烟应等待 stdin/stdout
|
||
bash <插件目录>/bin/deta-mcp.sh --profile writer
|
||
```
|
||
|
||
需要云侧能力（项目列表 / 新建项目 / 项目同步 / 打开 Studio）时：让助手调 `login` 工具 →
|
||
浏览器打开授权地址（首次输一次账号密码或邮箱验证码）→ 点「登录并授权」。**不需要终端**；
|
||
令牌自动写入 `~/.deta` 并即时生效，过期先静默续期。
|
||
|
||
命令行形态（无 `login` 工具）可用 `~/.deta/bin/deta login` 兜底，`~/.deta/bin/deta doctor` 自检。
|
||
|
||
## 安装（dsh）
|
||
|
||
```bash
|
||
export DETA_PLUGIN_ROOT=<本包所在目录>
|
||
dsh plugin --profile <name> add "$DETA_PLUGIN_ROOT"
|
||
# 验证配置层（不需凭据）：--dump-config 输出应含 serverName: writer_mcp / transport: stdio
|
||
```
|
||
|
||
## 文件
|
||
|
||
```
|
||
.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 登录助手（~/.deta/credentials.json + ~/.deta/env，供云侧能力用）
|
||
bin/deta-mcp.sh 本机 stdio 启动器（多产品共用；缺省 `--profile writer`）
|
||
README.md 本文件（连接形态 / 能力边界 / 排障）
|
||
skills/report-authoring/SKILL.md 宿主侧技能（报告写作取数与纪律；不含工具清单）
|
||
```
|
||
|
||
## 排障
|
||
|
||
- **工具面为空 / 宿主说没有工具**：先看宿主日志（Codex 桌面应用日志的
|
||
`mcp_server_startup_status_updated` 与 `logs_2.sqlite` 的 `omitting MCP server`），
|
||
再跑一次 `bash bin/deta-mcp.sh --profile writer` 看启动器 stderr 回显的运行时与工作区。
|
||
- **看到的是 Studio 的数据**：检查工作区是否被 `DETA_WORKSPACE` 覆盖成了 Studio 目录；
|
||
缺省档位下两者是隔离的（`~/.deta/writer/workspace` vs `~/.deta/studio/workspace`）。
|
||
- **命名空间重复**（`Duplicate namespace name …`）：上游代理问题，另起会话，不要重试。
|