添加代理目标
- 作者仓库星标 15
- 作者仓库 agentsmesh
- 领域
- 文档
- 作者声明的智能体
- 未找到明确声明;不据此推断已兼容或已测试
- 静态检查
- 88 / 100 · 启发式扫描,不代表运行安全
- 运行环境证据
- 未执行;当前没有隔离运行测试证据
- 作者 / 版本 / 许可证
- @sampleXbro · 未声明许可证
- 上下文用量评级
- 低消耗
- 接入复杂程度
- 需简单配置
- 是否需要外部接口密钥
- 不需要
- 兼容的系统
- macOS · Linux · Windows
- 运行环境要求
- 未检出明确要求
- 检测到的文件与系统行为
-
- 只读
- 允许写入 / 修改
- 命令执行
- 网络行为
- 仅限本地
- 安装命令数
- 无(仅作为资料)
需要注意: 未声明工具权限范围;实际权限由运行环境决定。
## Purpose
# Add Agent Target
Use this skill when the task is to add a brand-new supported agent target to this repository (built-in) or as an external plugin package.
**Primary reference**: `docs/add-new-target-playbook.md` is the step-by-step workflow (phases 1–9, file templates, verification gates). Open it first and follow it. This skill file is the contract — the non-negotiable rules, touchpoints, and completion bar. The playbook is how; this file is what and why.
**Companion skill**: `add-global-mode-target` — use only when extending global-mode support into an existing target that was built before global was a first-class contract. For new targets, global mode is part of this skill (scaffold wires it automatically).
## When To Use
- The task is to add a tool not currently in `src/targets/catalog/target-ids.ts`
- Scope covers both `project` and `global` modes unless the target has no meaningful global surface
- Delivery is either built-in (in this repo) or external plugin (standalone npm package)
## Do Not Use This Skill For
- Extending global-mode coverage on an existing target — use `add-global-mode-target`
- Changing capability levels for an existing target — update the target's descriptor directly
- Plugin feature work that doesn't add a new target id
## Non-Negotiable Rules
### MUST
- Search the internet for the target's current official file structure, config files, and example content before changing code.
- Prefer official docs and other primary sources. Use vendor examples or source code only when official docs are incomplete, and call that out explicitly.
- Separate the target product from the current assistant runtime before making format decisions. Do not confuse a generated target like `codex-cli` with Codex desktop/chat, or local CLI MCP config with app-managed connectors.
- Capture the target's real capability map for every canonical feature: rules, additionalRules, commands, agents, skills, mcp, hooks, ignore, permissions.
- Fill in the descriptor `metadata` block (`displayName`, `category`, `officialUrl`, `shortDescription`). This is required at compile time and drives every auto-generated tool list in README + website. The scaffold leaves `TODO(agentsmesh-scaffold)` markers — replace them with the values from your Phase 1 research before commit.
- When a feature is `none` but `skills` is `native` or `embedded`, evaluate whether `supportsConversion` should project that feature as skills. If the target reads skill bundles, commands and agents with no native surface should be projected as skills via `supportsConversion: { commands: true, agents: true }` and registered in `src/config/core/conversions.ts` with `DEFAULT_*_TO_SKILLS`. Do not add lint warnings for features that are projected as skills — only warn for features that are truly dropped.
- Start from `agentsmesh target scaffold <id>` when building a built-in target. Do not hand-write the 10 skeleton files the scaffold produces.
- Write failing tests first for every new behavior. Do not implement first and backfill later.
- Add unit, integration, and e2e coverage for the complete import and generate flow, including global scope when applicable.
- Add rich and realistic fixtures for the new target. Fixtures must resemble real projects, not toy placeholders.
- Cover all edge cases for the new target, including legacy paths, fallbacks, malformed files, partial support, and unsupported features.
- Wire descriptor capabilities for both project and global scope. New targets must include global mode unless the target has no global config surface at all, and that absence must be documented.
- Update every affected command surface and user-facing document so the new target is discoverable and accurately described.
- Update the compatibility matrix to reflect native, embedded, partial, or unsupported features. The matrix auto-builds from descriptor capabilities; `pnpm matrix:verify` must pass. The same script auto-generates the import-targets table, homepage tool list, and README tool list from descriptor `metadata` — no manual edits to those tables.
- Update init detection and import empty-state messaging for the new target when native files exist.
- Reuse existing capability-focused tests where possible; extend them instead of duplicating assertions across multiple files.
- Preserve the canonical `.agentsmesh/` contract. If the target cannot represent a feature natively, model that explicitly instead of inventing fake native output.
- Ensure every internal file link or reference inside generated or imported Markdown artifacts is convertible through the shared reference-rewrite pipeline, just like the existing targets. Do not ship a new target unless canonical `.agentsmesh/` references round-trip cleanly across that target's Markdown surfaces.
- Run the full verification stack, including the packaging gates (`pnpm attw`, `pnpm publint`, `pnpm consumer-smoke`), before claiming completion.
- Run the `post-feature-qa` skill before marking the task done.
### MUST NOT
- Do not infer the target format from old fixtures, README text, or memory alone.
- Do not add placeholder fixtures with `SYNTHETIC` markers or obviously fake content.
- Do not add shallow smoke tests as a substitute for feature coverage.
- Do not silently skip unsupported features; document and test the chosen behavior.
- Do not leave commands, schema enums, init detection, matrix output, or docs partially updated.
- Do not hardcode target-specific branches in shared code when a descriptor field can carry the behavior.
## Workflow (detailed in `docs/add-new-target-playbook.md`)
1. **Research** — §1 of the playbook. Answer every research-checklist item from primary sources before writing code.
2. **Scaffold** — §2 of the playbook. Run `pnpm exec agentsmesh target scaffold <id>`, then register the id in the three catalog files listed there.
3. **Constants and capabilities** — §3. Fill in paths and capability levels for both project and global scope.
4. **Conversion eligibility** — For each feature marked `none` in capabilities, check if the target supports skills (`native` or `embedded`). If so, add `supportsConversion` to the descriptor for those features, register defaults in `src/config/core/conversions.ts`, and omit lint warnings for those features (they become `embedded` via skill projection). Only emit lint warnings for features that are truly dropped with no fallback.
5. **Tests first** — §4. Add realistic fixtures under `tests/e2e/fixtures/<id>-project/` and write failing unit/integration/e2e tests.
5. **Implement generators, importers, and reference maps** — §5. Feature-by-feature, using existing targets as reference implementations.
6. **Global mode** — §6. Fill in `descriptor.global`, `rewriteGeneratedPath`, and any `skillMirror` or `sharedArtifacts` needs.
7. **Plugin packaging** — §7. Only if shipping as an external plugin rather than a built-in.
8. **Matrix and docs** — §8. Run `pnpm schemas:generate && pnpm matrix:generate` and update `website/src/content/docs/reference/supported-tools.mdx`.
9. **Verification** — §9. Run the full stack (see below). All must pass.
Refer to `.agentsmesh/skills/add-agent-target/references/target-addition-checklist.md` for the concrete audit list of touchpoints, tests, fixtures, and edge cases.
## Required Verification
Before claiming completion, every command must pass:
- `pnpm typecheck`
- `pnpm lint`
- `pnpm test`
- `pnpm test:e2e`
- `pnpm matrix:verify`
- `pnpm publint`
- `pnpm attw`
- `pnpm consumer-smoke`
If a narrower command is useful during iteration, run it first, but do not skip the full stack at the end.
## Completion Standard
The task is not done until all of the following are true:
- The target appears in `agentsmesh matrix` CLI output and passes `pnpm matrix:verify`.
- Import and generate behavior are both covered for every supported feature, in both project and global scope where applicable.
- Unsupported or lossy features are documented in `website/src/content/docs/reference/supported-tools.mdx` and tested.
- Fixtures under `tests/e2e/fixtures/<id>-project/` are rich enough to exercise real parsing branches (rules, skills, MCP, hooks, ignore as applicable).
- Round-trip import → generate preserves content byte-for-byte where the format permits.
- README matrix and website supported-tools page are in sync.
- All verification commands listed above pass.
- `post-feature-qa` skill has been applied and any gaps closed. 章节与文件索引
按说明文件中的顺序排列。
目的
何时使用
请勿将此技能用于
必须
绝不能
文件/命令 -> docs/add-new-target-playbook.md · add-global-mode-target · src/targets/catalog/target-ids.ts · project · global · codex-cli · metadata · displayName
内容校验值 -> 6c7a43c7129e
当前原文的自动摘译,尚未人工审校。
目的
添加代理目标 当任务是将全新的受支持代理目标添加到此存储库(内置)或作为外部插件包时,请使用此技能。主要参考:
docs/add-new-target-playbook.md是分步工作流程(阶段 1-9、文件模板、验证门)。先打开它,然后按照它。这个技能文件就是合同——不可协商的规则、接触点和完成栏。剧本是如何做的;这个文件是什么以及为什么。何时使用
任务是添加当前不在
src/targets/catalog/target-ids.ts中的工具 范围涵盖project和global模式,除非目标没有有意义的全局表面 交付是内置的(在此存储库中)或外部插件(独立的 npm 包)请勿将此技能用于
扩展现有目标上的全局模式覆盖范围 - 使用
add-global-mode-target更改现有目标的功能级别 - 直接更新目标的描述符 插件功能工作不会添加新的目标 ID必须
在更改代码之前,请在互联网上搜索目标当前的官方文件结构、配置文件和示例内容。更喜欢官方文档和其他主要来源。仅当官方文档不完整时才使用供应商示例或源代码,并明确指出。在做出格式决策之前,将目标产品与当前助手运行时分开。不要将生成的目标(如
codex-cli)与 Codex 桌面/聊天或本地 CLI MCP 配置与应用程序管理的连接器混淆。绝不能
不要仅从旧装置、自述文件或内存中推断目标格式。请勿添加带有
SYNTHETIC标记或明显虚假内容的占位符装置。不要添加浅冒烟测试来替代功能覆盖范围。不要默默地跳过不支持的功能;记录并测试所选行为。不要部分更新命令、模式枚举、初始化检测、矩阵输出或文档。