参考
辅助器
用于研究、审计、质量与编排的持久化辅助智能体，附带 frontmatter 契约和部署隔离协议。
持久化辅助器以扁平文件的形式存放在规范的辅助器目录下，使用 <name>.md 后缀。规范路径为：
src/apothem/agents/每个辅助器都是一个专注的角色，例如研究、审计、质量、重构或脚手架搭建，各有自己的工具限制和系统提示词。
下方的表格和路径列表展示了其中四个辅助器。本页末尾生成的清单列出了每一个辅助器定义。
| 辅助器 | 文件 | 模式 | 模型策略 |
|---|---|---|---|
| Codebase Explorer | 见下方清单路径 | 研究 | 由宿主选择 |
| Convention Auditor | 见下方清单路径 | 审计 | 由宿主选择 |
| Quality Gate | 见下方清单路径 | 质量 | 由宿主选择 |
| Memory Auditor | 见下方清单路径 | 审计 | 由宿主选择 |
规范的清单路径：
src/apothem/agents/codebase-explorer.md
src/apothem/agents/convention-auditor.md
src/apothem/agents/quality-gate.md
src/apothem/agents/memory-auditor.mdFrontmatter 契约
---
name: <agent name>
version: <semver>
updated: <YYYY-MM-DD>
description: <one-line role>
tools: <comma-separated tool list>
disallowedTools: <comma-separated deny list>
maxTurns: <integer>
---tools 是可选的。省略它的辅助器会继承会话拥有的每一个工具（包括已连接的 MCP 工具），并由 disallowedTools 承载其限制。全部十四个随附辅助器都列出了 tools。
已连接的 MCP 服务器
列出了 tools 的辅助器只能调用它所列出的内容。只有当条目指明服务器时（形如 mcp__<server>__*），Claude Code 才会将某个 MCP 工具纳入该列表；单独的 mcp__* 仅被文档化为 disallowedTools 条目，别处均无此用法。服务器名称属于连接它们的人，因此随附的辅助器无法指明这些名称。
citation-auditor 和 research-scout 负责查找学术来源。二者都随附 tools: Read, Glob, Grep, WebSearch, WebFetch，并拒绝那些写入文件、运行命令、启动其他辅助器或发布内容的工具：Write、Edit、MultiEdit、NotebookEdit、Bash、PowerShell、Monitor、Agent、Artifact，以及任务列表工具。在没有任何配置档案设置的情况下，二者都无法访问 MCP 工具，并通过网页搜索和网页抓取来查找来源。
要为其中一个辅助器提供已连接的学术索引，请在配置档案的 agent_mcp_servers 键中指明该服务器，该键将智能体名称映射到服务器名称。随后，Claude Code 引擎安装（apothem install）会为每个指明的服务器向该智能体的 tools 行追加一个 mcp__<server>__* 条目，且不改动任何其他智能体。Gemini CLI 安装也会这样做：对于由字母、数字和 - 组成的服务器名称，它会在该智能体的 tools 允许列表中为每个服务器追加一个 mcp_<server>_* 条目。在这两者上，智能体自身的 disallowedTools 所指明的服务器仍保持被拒绝。该条目会放行该服务器的每一个工具，包括任何会写入的工具，因此只应指明你信任其用于查询的服务器：辅助器的指令将它们限制为搜索、查找、读取、验证和解析调用，但工具只强制执行 tools 行所列出的名称。针对不存在的智能体、或没有显式 tools 行的智能体所给出的名称，会被报告并跳过。
Claude Code 和 Gemini CLI 以外的工具会忽略该键。Claude Code 插件树是在没有配置档案的情况下组装的，并保留普通列表，因此插件用户应改为在 ~/.claude/agents/ 下定义一个用户级智能体。配置档案语法、服务器名称规则以及该变通做法见让辅助器访问 MCP 服务器。
按工具转换
如果某个辅助器的 tools 授权在减去 disallowedTools 之后不包含任何文件编辑工具（Write、Edit、MultiEdit 或 NotebookEdit），它就是只读的。没有 tools 授权的辅助器，当 disallowedTools 至少拒绝了 Write 和 Edit 时即为只读。每个转换辅助器的工具要么原生地强制执行该限制，要么在辅助器的指令中声明该限制，要么去掉只读标签：
| 工具 | 工具限制 | 轮次限制 | 模型与推理强度 |
|---|---|---|---|
| Claude Code | 按原样使用 tools / disallowedTools，外加配置档案的 agent_mcp_servers 键向已列出的 tools 行添加的任何 mcp__<server>__* 条目；没有 tools 时，继承每一个工具，包括 MCP | maxTurns | 继承（未设置） |
| Codex | 不输出任何限制；辅助器的指令声明该限制，由父会话的沙箱管控写入 | 不可用 | 继承（未设置） |
| Gemini CLI | 由 Gemini 工具名称组成的 tools 允许列表，外加配置档案的 agent_mcp_servers 键向已列出的显式列表添加的任何 mcp_<server>_* 条目；没有 tools 时，使用拒绝项所隐含的允许列表加上 mcp_* | max_turns | 继承（未设置） |
| Qwen Code | 使用 Qwen 工具名称的 tools / disallowedTools；没有 tools 时，不输出列表，因此 MCP 工具被继承，拒绝项仍然生效 | 未映射 | model: inherit |
| OpenCode | permission（每个工具的 allow / deny）；MCP 工具不受限制 | 未映射 | 继承（未设置） |
| Antigravity | 不输出任何限制；描述中去掉“只读” | 不可用 | 继承（未设置） |
| CodeBuddy | 以逗号分隔字符串表示的 tools / disallowedTools，仅限 CodeBuddy 文档化的工具名称；无 MCP 条目 | maxTurns | 继承（未设置） |
| Trae | 以逗号分隔字符串表示的 tools / disallowedTools，仅限 Trae 文档化的工具名称；无 MCP 条目 | 不可用 | 继承（未设置） |
| GitHub Copilot | 由 Copilot 别名（read、search、edit、execute、web、agent、todo）组成的 tools 允许列表，并折入拒绝项，因为 Copilot 没有拒绝键；覆盖了被拒绝工具的别名会被略去；无 MCP 条目 | 不可用 | 继承（未设置） |
| Cursor | 没有工具列表（Cursor 不支持）；对五个不含 Bash 的只读辅助器使用 readonly: true，其他只读辅助器去掉“只读”标签 | 不可用 | 继承（未设置） |
| Kimi Code | 以 Kimi Code 工具名称列表表示的 tools / disallowedTools（WebFetch 变为 FetchURL，TodoWrite 变为 TodoList；Kimi Code 没有对应工具的名称会被略去）；无 MCP 条目 | 不可用 | 继承（未设置） |
| Kiro | 由 Kiro 工具类别（read、write、shell、web、subagent）组成的 tools 允许列表，并折入拒绝项，因为该列表是唯一写入的限制；覆盖了被拒绝工具的类别会被略去；无 MCP 条目 | 不可用 | 继承（未设置） |
| Windsurf | 由 Devin 工具名称（read、edit、grep、glob、exec、write）组成的 allowed-tools 允许列表，并折入拒绝项，因为 Devin 没有拒绝键；需要网页工具的三个辅助器不会被安装；无 MCP 条目 | 不可用 | Devin 的默认子智能体模型（未设置） |
Hermes 和 Open-Claw 以支持材料的形式接收辅助器文件，而不是将其作为原生辅助器。
编排
辅助器的部署、并行启动协议、返回契约的强制执行以及隔离纪律位于编排规则中。逐工作者的调度树位于编排模式规则的 §Decision Tree。规范路径：
src/apothem/rules/agent-orchestration.md
src/apothem/rules/agent-orchestration-patterns.md生成的智能体清单
| Name | Description | Source |
|---|---|---|
README | Persistent agent definitions — the reusable sub-agent specifications the harness materializes whenever the orchestrator deploys a research, audit, or quality team. Each agent is a | src/apothem/agents/README.md |
citation-auditor | Read-only citation audit — checks that each reference in a bibliography or cited passage exists, matches its record, and that the opened source states what the text attributes to it. Use when a draft cites sources: 'check my references', 'are these DOIs real', 'does this paper say what I cite it for'. Finding new sources routes to research-scout; a free-standing claim routes to fact-checker. | src/apothem/agents/citation-auditor.md |
codebase-explorer | Read-only codebase exploration — exhaustively find every instance of a pattern, trace call/import dependencies, discover host conventions, map architecture and layering. Use when the query is 'where is X used', 'find all callers of Y', 'what convention does this repo follow for Z', 'map the module structure', or 'trace what depends on this file' — never for edits or design, and never for review verdicts (architecture-review, code-audit). Works through Grep / Glob / Read plus read-only Bash and returns evidence-cited findings (path + line + snippet) exhaustive within the declared scope; reports gaps rather than guessing. | src/apothem/agents/codebase-explorer.md |
convention-auditor | Read-only conventions auditor: verify naming (kebab-case files, snake_case Python, frontmatter keys), cross-reference resolution (dead rule/skill/agent paths, broken anchors, half-edge bindings), formatting standards (SPDX header presence, frontmatter contract), and ecosystem coherence (orphan artifacts, sibling-convention drift, registry gaps). Dispatch when a change touches multiple rules/skills/agents/commands and you need a binary PASS/FINDING verdict per instance with file+line+expected+actual evidence — e.g. 'audit naming across the harness adapters', 'check every new rule resolves its Bindings cross-refs', 'verify the skills cohort matches the kebab-case + SKILL.md convention'. Read-only: never fixes, never runs shell. A whole-tree sweep, or any fix, is the ecosystem-audit skill. Conventions are owned upstream and verified against, never re-derived; every finding cites severity + evidence. | src/apothem/agents/convention-auditor.md |
dependency-auditor | Read-only dependency-tree risk audit — flags unpinned, stale, duplicate, and known-vulnerable dependencies with manifest/lockfile evidence. Dispatch within a dependency audit, before a release cut, or after adding a dependency; one named CVE or advisory routes to the vuln-triage skill, and a signing or provenance review to the supply-chain-audit command. Detects the ecosystem via host-discovery: npm (package.json + package-lock/yarn/pnpm), pip (pyproject/requirements + lock), cargo (Cargo.toml + Cargo.lock), go (go.mod + go.sum). Runs npm audit / pip-audit / cargo audit / govulncheck and returns a risk-ranked table (known-vulnerable → unpinned → duplicate → stale) with per-row evidence; never widens a pin or escalates a scope — gaps surface as inquiry. | src/apothem/agents/dependency-auditor.md |
design-critic | Read-only UI critique. Use for a design review, a usability or accessibility check, or 'what is wrong with this screen' before a UI ships. A WCAG sweep across a whole web surface routes to the a11y-audit command; a CLI or install-flow review to ux-review. Reviews code, screenshots, or a running page and returns fixes ranked by user impact, from a scored heuristic review and separately measured evidence. Opens with a degraded notice when measurement tooling is missing; never guesses a measurement. | src/apothem/agents/design-critic.md |
fact-checker | Read-only adversarial claim verification — decompose input into atomic claims, seek ≥2 independent sources, attempt refutation, assign cited verdicts (supported / refuted / unverifiable) with quoted evidence and confidence. Use when a claim needs proof before it ships: a benchmark or statistic in docs/copy, a 'X is faster/safer than Y' assertion, a citation that names an RFC or spec, a release note, or any factual claim a reviewer would challenge. Routes external claims through WebSearch / WebFetch and repository claims through Read / Glob / Grep; defaults to refuted-or-unverifiable when evidence is insufficient, never a charitable supported. | src/apothem/agents/fact-checker.md |
mcp-builder | Scaffold a Model Context Protocol (MCP) server skeleton from a tool/resource contract — contract-first, well-typed tools, minimal surface. Use when: 'build an MCP server for <API>', 'scaffold MCP tools from this spec', 'wire FastMCP/TypeScript-SDK tool definitions', 'add a tool that exposes <resource> over MCP'. Detection: tool names + argument shapes + return types + resource URIs are stated or derivable. Selects the SDK via host-discovery (FastMCP for Python, the TypeScript SDK for Node), emits one typed tool definition per contract entry plus a list-tools smoke test, and scaffolds nothing speculative. Not for: tuning, securing, or load-testing an existing server (those surface as adjacent gaps). | src/apothem/agents/mcp-builder.md |
memory-auditor | Read-only memory-file auditor: cross-reference every claim in the harness memory tier (MEMORY.md index + topic files under <harness-root>/projects/{hash}/memory/ and <harness-root>/memory/) against actual filesystem state — file/line/rule counts (glob and count), referenced paths (do they exist?), rule scope labels (match pathFilter frontmatter?), dates (against frontmatter updated: or mtime, never the system clock), and cross-reference matrices. Dispatch when MEMORY.md or a topic file may have drifted from reality and you need a per-claim PASS/FAIL verdict with contradicting evidence — e.g. 'audit MEMORY.md after the rules cohort was renamed', 'verify the memory index counts match the current ecosystem', 'check the debugging topic file for stale references to deleted artifacts'. Existence + name match only; never re-audit an artifact's internal correctness (convention-auditor's scope). Read-only: never writes, never fixes. | src/apothem/agents/memory-auditor.md |
prompt-evaluator | Read-only rubric scoring of a prompt's output set — score each output against each named criterion (PASS/FAIL with cited evidence), aggregate per-criterion pass-rate, flag regressions against a baseline, and name recurring failure modes. Use when prompt or model outputs need a reproducible verdict before they ship: comparing a reprompted variant against the prior version, gating a system-prompt change, judging an LLM-as-judge eval set, scoring few-shot outputs against acceptance criteria, or proving a quality claim a reviewer would challenge. Scores outputs that already exist: building the dataset, scorer or runner routes to the eval-harness skill, and a full campaign to the eval command. Requires an explicit rubric — an absent or underspecified rubric blocks scoring and routes as inquiry; never invents a criterion or threshold, never scores charitably. | src/apothem/agents/prompt-evaluator.md |
quality-gate | Read-only quality-gate runner — discovers the host's lint / type-check / test / security / build commands, runs them in the correct order (build → type-check → tests+lint+security in parallel), and returns a per-gate PASS/FAIL verdict with file+line+error evidence. Reports, never fixes. Dispatch as a Quality team before a release cut, after a multi-file change, or to confirm a fix is green — e.g. 'run the full quality matrix and tell me what fails', 'gate this branch before I push', 'is the test suite green and the types clean?'. Runs the whole matrix; tests alone route to test-runner. Detects tooling via host-discovery (ruff/eslint/markdownlint, mypy/tsc/pyright, pytest/jest/cargo test/go test, bandit/npm audit/gitleaks); never assumes a stack. | src/apothem/agents/quality-gate.md |
refactor-surgeon | Scoped, behavior-preserving refactor of a named target — extract the behavioral contract, re-derive clean-room (never edit in place), name the one deficiency removed, verify regression via the host's own tests. Dispatch as a delegated team member on a single named target with a clear refactor intent; a user-driven interactive extraction is the refactor-extract skill — e.g. 'consolidate the duplicated validation in the CLI's install module', 'untangle the nested conditionals in the config renderer without changing output', 'rename the god-object methods in the adapter class to reveal intent'. Touches only the named target; adjacent gaps surface as findings, never as edits. Behavior, contracts, and side effects are identical before and after; a behavior change is a defect. | src/apothem/agents/refactor-surgeon.md |
research-scout | Read-only source discovery and ranking — decompose a research question into facets, fan out parallel web queries, rank candidates by authority, recency, and relevance, and return a deduplicated ranked source list. Use when a question needs sources before it can be answered: 'find the authoritative spec/RFC for X', 'what are the primary sources on Y', 'gather current references for a docs/copy claim', 'survey the landscape before a deep dive'. Fans external facets through any scholarly index server the operator has granted it, WebSearch, and WebFetch, and any in-repo corpus through Read / Glob / Grep. Also looks up papers and preprints by DOI, arXiv id, or topic ('find the paper behind this DOI'), and scouts existing open-source projects before anything new is built ('is there already a library for this', 'adopt or fork'). Discovery and ranking only — never fabricates a URL, never synthesizes; a written cited report routes to the multi-source-research skill, claim verification to fact-checker, and combining given documents to source-synthesis. | src/apothem/agents/research-scout.md |
security-scanner | Read-only secret, SAST-pattern, and config-risk sweep — a coarse first-pass that surfaces candidates fast and routes deep scanning to the host's CI scanners. Dispatch inside a security audit, after touching auth/crypto/IO surfaces, or when a secret may have been committed; a full repository security audit routes to the security-audit command. Greps for credential literals (key/token/password/private-key/certificate, committed .env values), injection surfaces (shell=True on untrusted input, string-formatted SQL, command interpolation), unsafe-eval (eval/exec/Invoke-Expression), unsafe deserialization (pickle.loads, yaml.load without SafeLoader), and config risk (over-broad CI permissions:, unpinned Actions uses:, network egress). Routes known-vulnerable dependencies to the dependency-auditor agent, CVE/advisory triage to the vuln-triage skill, and leaked-credential rotation to the secret-rotation skill. | src/apothem/agents/security-scanner.md |
test-runner | Read-only test-suite runner — discovers the host's test command, runs it, and triages every failure by root cause with test+file+line+assertion evidence. Reports, never fixes. Dispatch as a Research/Quality team member after a code change, before a release cut, or to confirm a fix is green — e.g. 'run the tests and tell me what's failing and why', 'is the suite green on this branch?', 'triage the failures in the auth module'. Tests only: lint, type and security gates route to quality-gate. Detects the runner via host-discovery (pytest/jest/cargo test/go test/Makefile target from the manifest + CI config); never assumes pytest. | src/apothem/agents/test-runner.md |