certd Certd 在线插件开发 Skill
开发方式
本 Skill 使用 Certd HTTP API，不使用 WebSocket，也不依赖浏览器传递代码草稿。
- 前端只生成包含需求、API 地址和认证 Token 的启动提示词。
- Agent 直接调用 Certd API 读取和保存插件 YAML。
- Agent 的进度、日志和代码修改在 Codex/Trae 中查看。
- 插件开发临时文件和修改历史统一保存在 Agent 工作区的
.plugin-dev/下，不保存到浏览器或 Certd 后端。
启动检查
开始开发前先确认当前工作目录是否已经在 Certd 项目内：
- 应存在
package.json。 - 应存在
packages/ui/certd-server/src/plugins/。 - 应存在
.trae/skills/。 - 应存在
.trae/skills/certd-online-plugin-dev/SKILL.md。
如果当前目录不是 Certd 项目，或缺少 certd-online-plugin-dev Skill，先拉取 Certd 仓库代码并切换到仓库内工作( --depth 1 拉取第一层即可)：
- 优先使用
https://atomgit.com/certd/certd/。 - 如果 AtomGit 拉取失败，再使用
https://github.com/certd/certd。 - 拉取后重新检查上述特征，并读取
.trae/skills/certd-online-plugin-dev/SKILL.md。
开发插件时，参考 Certd 项目下已有内置插件实现：packages/ui/certd-server/src/plugins/。
插件来源
Certd 插件按来源分为三类：
- 内置插件：
type: "builtIn"，随 Certd 安装包提供。可读取并在流水线中使用，不应通过本 Skill 修改或覆盖。 - 市场插件：
type: "store"，且存在appId或developerId。它来自在线插件市场，可能尚未安装到本地；是否可修改只能以接口返回的editable为准。 - 本地插件：
type: "store"，但没有appId和developerId。它是当前 Certd 实例本地创建、导入或复制的插件，可直接保存；发布到市场后会带上市场归属信息。
不要只根据 type: "store" 判断插件是否来自市场，也不要自行推断编辑权限；始终使用列表结果中的 editable 字段。
API 认证
提示词会提供 Certd API 地址和仅限 AI 插件开发接口的受限 Token。调用 API 时使用：
Authorization: <token>
Content-Type: application/json
不要把 Token 写入代码、历史摘要、日志、提交信息或插件 YAML。
所有 Certd API 请求统一使用 Node.js 的 fetch。不要使用 PowerShell 的 Invoke-RestMethod、Invoke-WebRequest 或 .NET HTTP 客户端发送插件 YAML/JSON；它们在 Windows 上可能造成中文乱码或使完整 YAML 导入请求长时间无响应。
Node 请求须直接读取 UTF-8 文件或在 Node 内构造 JSON，并使用 JSON.stringify：
const response = await fetch(`${apiBase}/scoped/sys/ai/plugin/find`, {
method: "POST",
headers: { Authorization: token, "Content-Type": "application/json; charset=utf-8" },
body: JSON.stringify({ keywords: ["nginx"], includeBuiltIn: true, includeStore: true }),
})
UTF-8 保存
在 Windows 上，Node 直接以 UTF-8 读取 YAML 并用 JSON.stringify 发送；不要让 PowerShell 转发含中文的 YAML/JSON。保存后检查中文字段不含 ?，再调用 /scoped/sys/ai/plugin/find 或 /scoped/sys/ai/plugin/info 验证。
API 工作流
- 使用
/scoped/sys/ai/plugin/find查询插件和 Access，可通过keywords数组传递多个关键词。 - 查询结果包含
editable：editable: true：允许当前 Agent 修改并保存。editable: false：只能读取和使用，不能修改。
- 读取完整 YAML 时调用
/scoped/sys/ai/plugin/export。 - 所有插件保存统一调用
/scoped/sys/ai/plugin/import，并始终传递完整 YAML：- 新插件使用
override: false。 - 已有插件使用
override: true；导入接口根据author和name定位并覆盖已有记录。
- 新插件使用
- 不使用
/sys/plugin/add或/sys/plugin/update保存插件，避免保存路径分叉、字段丢失和 Windows 请求兼容性问题。 - 保存完成后重新调用
/scoped/sys/ai/plugin/find或/scoped/sys/ai/plugin/info验证结果。
/scoped/sys/ai/plugin/find 会在一次请求中分别查询内置插件和 store 插件，再合并返回；store 插件需按上述字段区分市场插件与本地插件。
详细请求字段见 references/certd-api.md。
Access 协作
开发 Task 或 DNS Provider 前，先用 /scoped/sys/ai/plugin/find 查询对应 Access：
- 如果没有对应 Access，先创建 Access 插件，再创建业务插件。
- 如果已有 Access，先读取它的完整 YAML 和
content。 - 如果 Access 已提供所需 API/SDK，业务插件优先复用。
- 如果缺少能力：
editable: true：优先修改 Access，并先保存历史。editable: false：在当前业务插件中实现必要的 API 调用。
- 业务插件通过
dependPlugins声明 Access 依赖。
详细规则见 references/access-development.md。
本地历史
开发插件时，必须在当前工作区创建并使用 .plugin-dev/{plugin-name} 作为插件开发目录。历史记录、临时 YAML、脚本草稿和调试记录都放在该目录下。
每次修改插件前，必须将完整 YAML 保存到 .plugin-dev/{plugin-name}/history/：
.plugin-dev/{plugin-name}/xxxxx.yaml
.plugin-dev/{plugin-name}/history/
2026-08-02T12-30-00-before-edit.yaml
2026-08-02T12-30-00-change.md
保存要求：
- 修改前保存完整 YAML。
- 修改后保存修改摘要。
- 恢复前再次备份当前版本。
- 不上传历史文件，不保存 Token、证书、私钥或真实授权值。
详细格式见 references/local-history.md。
YAML 和脚本规范
插件始终以完整 YAML 传递和保存，脚本源码放在顶层 content 字段。
- 统一使用
await _ctx.import(...)引用模块。 "/@/..."表示以绝对路径引用server/src/下的模块。- 最后返回继承目标基类的 class。
- 不使用
import、export、装饰器或独立源码文件语法。 - 使用
this.logger打印插件执行日志。 - 使用
this.ctx.http访问 HTTP 能力。 - 失败时抛出
Error。
需要字段格式时读取 references/online-yaml-format.md。
需要组件示例时读取 references/component-examples.md。
示例插件
开发对应类型插件前，先读取 examples/ 下的示例：
- Access：
examples/DemoAccess.yaml - 部署/Task：
examples/DemoDeploy.yaml - DNS Provider：
examples/DemoDnsProvider.yaml
示例是完整在线插件 YAML，重点参考 input 配置、依赖声明和 content 脚本结构。
子 Skill
- Task：
skills/task-plugin-dev/SKILL.md - DNS Provider：
skills/dns-provider-dev/SKILL.md - Access：
skills/access-plugin-dev/SKILL.md
安全边界
Certd 会保存证书、私钥、API Token、云厂商密钥、SSH 凭据和其他敏感授权。
- 禁止读取、打印或上传真实授权值。
- 禁止把认证 Token 写入插件、历史、日志或摘要。
- 禁止读取无关的证书、私钥、Cookie、环境变量和系统设置。
- 只使用脱敏示例数据和公开文档。