Unified AI MCP Tool

专家

一台MCP服务器。许多专业代理商。珠联璧合。

Specialist是一个项目范围的运行时，用于从CLI、MCP、脚本、CI或HTTP sidecar运行专注的AI代理。专家定义声明了它的模型、工具、权限层、提示、技能、输出契约、超时/暂停策略、工作树行为和跟踪行为。编排器将任务标识保存在 珠子专家们以新的范围会议的形式运行，将证据、变化和结果报告给那个珠子。

专家坐在xt/xtrm堆栈中：

• pi编码剂 提供模型/提供者执行层、JSONL/RPC子流程边界、工具事件和扩展挂钩。
• xtrm工具 提供周围的操作员工作流程：工作台会话， .xtrm/ 技能/挂钩、会话报告、更新工具和工作流执行。
• 珠子 供应问题ID、依赖关系边、声明和持久任务/结果注释。

当跑步开始时 --bead ，珠子是任务提示。可以注入依赖上下文和相关内存，将专家输出附加回同一个珠子上，具有编辑能力的专家在孤立的分支/工作树中工作，这些分支/工作树可通过以下方式进行查看和合并 sp merge 或 sp epic merge.

______________________________________________________________________

视觉

专家将一个超载的代理聊天变成一个协调的代理思维：一个中央编排器保持任务身份、证据和发布控制，而新的专家会话则作为范围内的功能，具有自己的提示、规则、工具、内存和输出契约。

它解决的问题不仅仅是令牌计数。长时间的单代理会话积累了旧的假设、部分计划、工具残留、自我审查偏见和被遗忘的约束。专家使用 契约约束认知 相反：编写一次任务契约，仅使用相关上下文分派正确的专家角色，要求进行结构化切换，并让编排者决定下一步。

看 专业人员.scheme.md 查看完整的图表和原理。核心形状为：

flowchart TD
  U[User / project need] --> O[Orchestrator]
  O --> B[Bead issue contract]
  B --> C{Contract ready?}
  C -->|no| R[Repair scope, success, constraints]
  R --> B
  C -->|yes| D[Dispatch specialist]

  D --> E[Explorer\nfresh read-only context]
  D --> G[Debugger\nfresh root-cause context]
  D --> X[Executor\nfresh implementation context]
  D --> T[Test-runner\nfresh validation context]
  D --> S[Code-sanity / Security\nadvisory context]
  D --> V[Reviewer\ncontract compliance context]

  B --> E
  B --> G
  B --> X
  B --> T
  B --> S
  B --> V

  E --> H[Structured handoff / evidence]
  G --> H
  X --> H
  T --> H
  S --> H
  V --> H
  H --> O
  O --> P[Merge, resume, re-review, or close]

你能跑什么

实时注册表具有权威性：

sp list
sp list --compact
sp list-rules
sp help

安装并引导

专家是 只包 并期望显式安装xtrm工具。xtrm工具是运行时的先决条件，而不是此包的npm依赖项。

# 1. Bun
curl -fsSL https://bun.sh/install | bash
bun --version

# 2. xtrm-tools
npm install -g xtrm-tools
xt install
xt init

# 3. Specialists
npm install -g @jaggerxtrm/specialists
sp init
sp doctor
sp list

sp 是的别名 specialists.

sp init 是一个交互式的、人工运行的引导程序。它检查 xt 和 .xtrm/，电线项目MCP注册，钩子，技能符号链接， .specialists/ 运行时目录和Specialist块 AGENTS.md确实如此 不 要求将包拥有的默认值复制到每个回购中。

更新和漂移修复

专家使用两种分销渠道：

.specialists/user/ 是您的自定义层。 .specialists/default/ 现在仅用于有意引脚或兼容性快照；过时的默认文件是漂移债务和 sp prune-stale-defaults 默认情况下删除它们。 sp init --sync-defaults 它仍然是一个兼容性路径，但已被弃用，因为它创建了可能偏离包规范源代码的repo本地快照。

核心跟踪工作流程

bd create "Investigate auth bug" -t bug -p 1 --json
bd update  --claim --json

sp run debugger --bead  --context-depth 3
sp ps
sp feed  --follow
sp result 

# After implementation and reviewer PASS
sp merge           # standalone chain
sp epic status             # multi-chain publication check
sp epic merge              # canonical epic publication

bd close  --reason "Done" --json

临时工作仍然可用，但跟踪工作应使用珠子：

sp run explorer --prompt "Map the CLI architecture"

后台作业和监控

正常运行时是DB优先： .specialists/db/observability.db 存储作业、事件和结果。文件镜像位于 .specialists/jobs/ 是传统/运营商恢复表面。

有用的命令：

sp ps                         # actionable dashboard
sp ps -f                      # TTY dashboard follow; pipes emit ANSI-free snapshots
sp feed               # full DB-backed event replay
sp feed -f                    # follow all active jobs
sp result  --wait
sp steer  "focus only on X"
sp resume  "continue with these findings"
sp finalize    # cascade-close waiting keep-alive chain after PASS if needed
sp clean --reap-orphans --dry-run
sp clean --ps                 # hide terminal dashboard history without deleting DB audit rows

脚本和服务专家

使用 sp run 用于交互式代理编排。当您需要同步的READ_ONLY一次性生成路径时，请使用脚本/服务界面：

sp script  --vars key=value --json
sp serve --port 8000 --readiness-canary warn
curl -sS http://localhost:8000/v1/generate \
  -H 'content-type: application/json' \
  -d '{"specialist":"hello","variables":{"name":"world"}}'

sp serve 旨在作为脚本类专家的sidecar。对于容器部署，挂载整个 .specialists/ 目录读写，设置 HOME=/pi-home，并将容器UID/GID与主机用户对齐。看 文档/专家服务.md, docs/specialists-service-install.md，以及 docs/deploying-alongside.md.

文档地图

项目结构

config/
├── specialists/       package-canonical specialist definitions (.specialist.json)
├── mandatory-rules/   package-canonical rule sets injected into specialist prompts
├── catalog/           package-canonical tool catalog
├── nodes/             package-canonical node configs
├── hooks/             bundled hook scripts
└── skills/            repo-local skills shipped by this package

.specialists/
├── user/              repo-owned specialists and overrides (highest precedence)
├── default/           optional pins / compatibility snapshots; prune stale files
├── mandatory-rules/   legacy/repo rule overlay compatibility
├── db/                runtime SQLite state (gitignored)
├── jobs/              legacy runtime mirror (gitignored)
└── ready/             legacy ready markers (gitignored)

.xtrm/
├── skills/            xtrm-managed skill snapshots and active links
└── hooks/             xtrm-managed hook snapshots

src/                   CLI, server, loader, runner, supervisor, MCP tool

核心规则

• 使用 --bead 用于跟踪工作；使用 --prompt 仅适用于快速无跟踪的工作。
• --context-depth 控件完成依赖上下文注入；焊道焊道的默认值为3。
• --no-beads 禁用跟踪珠创建/更新，但在以下情况下不会禁用读取输入珠 --bead 提供。
• 编辑能力强的专家在独立的工作树中运行。审查/修复通行证应使用 --job 重复使用相同的工作空间。
• 审阅者PASS是发布门户。代码健全性/安全性/测试运行器输出是咨询证据，而不是合并批准。
• 专家是项目范围内的。用户范围专家发现已弃用。

弃用的命令

这些命令仍被识别为迁移指导，但不再是入职路径：

• specialists setup
• specialists install
• sp release prepare / sp release publish （弃用别名；发布流程由技能驱动）

使用 sp init, xt update，而释放技能流。

发展

bun run build
bun test           # bun vitest run (default)
bun run test:node  # node vitest run (subprocess-safe alternative)
sp help
sp quickstart

许可证

麻省理工学院——见 许可证.