connection-authoring

Files (6)

• SKILL.md
• connection-contract.md · references/
• SKILL.md · templates/
• client.mjs · templates/
• commands-and-results.md · templates/
• connection.yml · templates/

SKILL.md (first lines)

# 制作外部系统接入

交付能被不同智能体（Agent）发现、维护和接续的完整技能（Skill）。先说明当前要解决的目标和必要决定，按需展开依据；遵守工作空间（Workspace）的沟通、授权和术语规则，不把内部步骤变成逐项人工确认。源资产制作不自动授权安装、真实登录或业务写入。

## 核对真实能力

核对系统的权威资料、已授权现场、可用接口（API）与工具（Tool），区分已验证、建议和未知。确定需要的配置、完整认证组、认证目标、实际操作对象和结果层次。类别（Category）只表达用途，不强制同类拥有相同专业动作。不能根据页面按钮宣称尚未验证的写入可用。

围绕用户要完成的代表性场景判断接入是否完整：用户通常提供目标和业务线索，方法应说明如何从代码、登记或外部查询找到准确对象，如何选择连接及执行工具（Tool），以及如何核验结果和处理失败、未知。说明无法支持的场景及必要输入，不按功能数量评估，不要求所有接入具有相同动作。

## 制作完整源目录

按系统真实身份模型声明认证来源：只允许个人授权的系统使用 `authentication.allowedSources: [personal]`，不把某个人的环境或审批权限固定成所有账号的权限。远端系统决定当前账号能看、能做什么；用户授权本次动作，专业程序另行说明已实现及已验证范围。多人共用一个个人账号也不改变其远端身份。此模式的实例文件只共享非秘密配置，完整个人组加密保存在规范工作空间（Workspace）`.buildr/local/` 私有忽略目录，本机密钥不随文件共享；显式查看已保存个人秘密不改变认证组，也不允许把原值写入提示词（Prompt）或普通结果。

外部登录返回的用户编号或会话令牌不应要求用户手工复制。系统需要浏览器授权时，声明 `authentication.authorization`，由专用程序接收本次授权并经私有通道交回完整个人组；界面使用授权与重新授权入口，不显示内部字段。程序须说明浏览器依赖、取消和资源清理，不从日常浏览器资料或其他账号借用认证。一个连接覆盖多个环境时，使用 `presentation.environment: hidden` 隐藏连接环境标签，专业操作仍明确选择环境；该展示策略不决定远端权限。

从当前技能（Skill）入口相对位置读取 [接入约定](references/connection-contract.md) 和 `templates/`。将模板 `SKILL.md` 放到入口、`connection.yml` 放到 `assets/`、`client.mjs` 放到 `scripts/`、`commands-and-results.md` 放到 `references/`，再修改名称与真实能力；不冒用既有技能（Skill）身份。需要持续集成与交付（CI/CD）等专业操作时，按真实能力声明程序并通过通用 `buildr connection-skill run` 调用，不依赖服务本地运行模块提供部署入口。所有新连接技能源统一放在用户自己的 `skills/connections/<skill-id>/`：

```text
skills/connections/<skill-id>/
├── SKILL.md
├── assets/connection.yml
├── scripts/client.mjs
└── references/commands-and-results.md
```

`SKILL.md` 说明适用目标、能力、对象定位、授权与副作用、工具（Tool）用法以及成功、失败、未知结果的核验和接续。声明维护类别与系统名称、管理字段、认证组、程序、有限槽位及表单区块顺序。让用户先选系统，再填地址和认证，再选择发现的业务范围；低频选项使用默认折叠区块，个人覆盖由 Buildr 提供次要入口。程序可以随附，也可由该技能（Skill）自行声明独立安装方式和依赖，不要求专业命令先进入 Buildr 公共目录。不复制旧产品模块作为运行时导入，不要求每个系统制作完整控制台。

模板没有真实实例配置或凭据；实际团队账号密码保存到用户明确选择的团队实例文件，个人组仅保存在本机，均不嵌入技能源、示例、任务材料或公开发布物。专业程序通过私有通道接收明确选择的上下文（Context），业务标准输入（Standard Input）留给专业数据。帮助和 `--self-test` 不接收上下文（Context）或认证、不访问真实系统；模板的 `test/discover` 通过 Buildr 接收明确的模拟实例，仅证明协议，不证明真实连接可用。

实例文件由 Buildr 按“系统＋环境＋唯一后缀”命名；完整 `id` 是稳定身份，实际路径从 `sourcePath` 取得，技能（Skill）与程序不手拼路径。同系统、同地址的不同实例可以并存：方法须说明如何核对目标范围和用途，仍有同等候选时请用户明确选择，不能按文件名、名称或列表顺序决定。

## 检查、登记与绑定

先执行该成果的离线检查和模拟验证，覆盖声明路径、未知字段、身份冲突、缺依赖、完整个人组覆盖、秘密回显、写前版本再核验和未知结果调查。槽位（Hook）按接入约定输出单个 JSON 对象，分别验证成功、失败、未知和无效输出；不能用退出成功代替有效 `status`。专业写入程序（Program）另行验证明确对象、写前版本保护与结果核验；受理不表述为成功，未知结果先调查，不自动重试。用两条同类同目标、不同 `id` 的实例分别执行，确认所选配置、认证和观察版本（Observed Revision）不串用；文件名或显示名称不成为调用身份。记录实际命令及结果；未执行真实验证就明确写未验证。模板程序只提供协议与模拟选项，不是已完成的业务适配。

有独立智能体（Agent）可用时，让其按交付的方法执行一个代表性场景，从用户原始线索完成对象定位、明确连接、专业操作和结果核验；提供必要原始资料，避免提前给出预期对象或答案。无法独立试用时记录实际缺口，不冒充已独立验证。有条件时在获授权的真实范围验证，其余使用适合的隔离现场或模拟；无真实授权不为验收擅自登录或写入。帮助、登录或通用连接测试通过不能替代专业场景验证，读取也不能替代发布或业务效果。按实际证明范围记录结果，独立验证发现缺口时补方法或工具（Tool），不把推理固化成不必要的通用模块。

按当前 `buildr skills add --help` 将完整源目录登记；`SKILL.md` 可声明 `connectionDefinitions: [assets/connection.yml]`，也可使用重复 `--connection-definition <relative-file>` 参数。新连接源会复制到 `skills/connections/<skill-id>/`；若已在标准位置制作，也可由现有技能（Skill）页面登记。唯一登记仍是 `skills/manifest.yml` 的 `path: connections/<skill-id>`，不是扫描目录即启用，也不建立第二套加载器。通过 `buildr connection-skill definitions list --json` 检查解析结果，按已授权范围投射到当前智能体运行时（Agent Runtime）。安装新技能（Skill）只增加可选项；实例另行明确绑定，不能静默替换现有同系统实现。

只有获得相应范围授权后才准备依赖、真实登录、测试或业务写入。分别报告源已制作、已登记启用、程序可执行、真实连接验证及业务目标核验；不要用退出成功替代业务成功。

专业结果涉及秘密、准确对象标识、原文或后续授权依据时，让方法提供调用方明确选择的受限本机产物（Artifact），说明原样读取和接续方式。普通输出可能经过秘密隐藏，只用于展示；不把改变后的标识或正文复制为写入依据。采用系统适合的方式，不要求所有方法使用同一命令或结果文件参数。

## 升级与停用

稳定身份不因同源替换或文档改变而变化。目录与接入声明保持标准结构；已有实例绑定不因安装另一同系统方法而改变。声明格式使用 `schemaVersion`，配置不兼容时提升 `configVersion` 并说明迁移差异；更新来源或认证接收方必须明示，不按同名接管。共享身份仅记录声明接收方，不包含本机可执行文件绝对路径；实际程序位置改变后重读当前观察再继续。停用或缺依赖时保留实例配置及认证，仅暂停相关动作。换机器重新检查程序及依赖；没有个人组时使用团队组，失效个人组不能自动回退。

From BuildrAI/Buildr, MIT.

More from BuildrAI/Buildr