deta/deta-agent-plugins
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
63d52f47b5c5a50b717e80bb86d37f50142662d8
deta-agent-plugins/README.md
T

9.4 KiB
Raw Blame History

DETA — Agent Plugins

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

能力本体（AML 建筑模型读写、编译校验、围护结构统计、空间邻接查询）以 MCP 服务提供， 同一份后端与技能被所有宿主复用；新增宿主只需再加一层声明式壳。

安装（Codex）

# 从 Git（分发用）
codex plugin marketplace add https://git.deta.city/deta/deta-agent-plugins.git

codex plugin list
codex plugin add deta@deta

# 登录（一次性）：打开浏览器完成 deta.city 账号登录
codex mcp login deta_mcp

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：

node ~/Dev/ant/deta-agent-plugins/plugins/deta/bin/deta-login.mjs
source ~/.deta/env        # 让 DETA_TOKEN 进入当前 shell 环境

未登录时 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 账号、不隔离工作区，仅供本机迭代领域能力：

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 版本号再重装：

python3.11 ~/.codex/skills/.system/plugin-creator/scripts/update_plugin_cachebuster.py \
  ~/Dev/ant/deta-agent-plugins/plugins/deta
codex plugin add deta@deta

（版本号形如 0.1.0+codex.20260910020424；重装后需开新会话才能加载新技能。）

校验清单：

python3.11 ~/.codex/skills/.system/plugin-creator/scripts/validate_plugin.py \
  ~/Dev/ant/deta-agent-plugins/plugins/deta
codex plugin marketplace list
codex mcp list | grep deta

双壳架构（Codex + dsh 同一产物）

plugins/deta/ 这一个目录同时是 Codex 插件根与 dsh 组合包根，共享核心、各带一层薄壳：

组成 文件 Codex dsh
插件清单 .codex-plugin/plugin.json ✅ 使用 —
MCP 声明 .mcp.json ✅ 使用（可放 Codex 私有键） —
组合包声明 package.json（dsh.bundle.patch） 忽略 ✅ 使用
配置层 cordis.patch.yml 忽略 ✅ 使用
领域技能 skills/aml-design/SKILL.md ✅ 共享 ✅ 共享
本地启动器 bin/deta-mcp.sh ✅ 由配置层的 args 直接指向服务入口

共享面（两端一致，零适配）：

  • 技能文件格式：<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 的声明位置不同（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 没有官方市场。

dsh 侧安装与验证

# 安装进某个 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

# 只验证配置层是否合并正确（不启动、不需凭据）
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 行

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（削弱并发触发面，长会话仍复现）。

应对：完成一个任务后另起会话；撞到该错误不要重试，重开会话即可（工作区文件保留）。

已修缺陷（实测）

现象 根因 修复
写类工具返回 user cancelled MCP tool call MCP 工具默认需审批，非交互模式下无法弹窗 .mcp.json 加 default_tools_approval_mode: "approve"（实测 auto/writes 都会被取消，只有 approve 放行）
并发调用触发命名空间重复 代理并发序列化 .mcp.json 加 supports_parallel_tool_calls: false

目录结构

.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）
├── package.json                        # dsh 组合包声明（dsh.bundle.patch）
├── cordis.patch.yml                    # dsh 配置层（挂载 MCP 服务）
├── bin/deta-login.mjs                  # 登录助手（~/.deta/credentials.json + ~/.deta/env）
├── bin/deta-mcp.sh                     # 本地 stdio 启动器（开发用，默认关闭）
├── README.md                           # 插件说明（安装/凭据/401 语义）
└── skills/aml-design/SKILL.md          # 领域技能（两宿主共享）
Reference in New Issue View Git Blame Copy Permalink