高级应用

这一章把 czagent 当成平台来用：定制 Agent、沉淀技能、接入外部工具、写代码编排一切。

一、自定义 Agent

「设置 → Agent」里除了内置的 Build / Plan，可以新建自己的 Agent：

系统提示词：定义角色与工作方式，例如「你是数据清洗助手，只处理 CSV，输出前必跑校验」；
工具开关：逐条勾选可用的内置工具与 MCP 工具；
权限：allow / deny / ask 逐工具设置；
模型与步数：指定默认模型，可设步数上限防止失控。

新建会话时选它，侧栏会显示 Agent 名；脚本里也能用 ctx.agent.run(prompt, { agent: '名称' }) 调度。

二、工具矩阵与权限规则

「设置 → 权限」提供 21 个内置工具的矩阵视图，每行两件事：

加载：是否注入给模型（关掉后模型看不见这个工具，但脚本直调不受限）；
权限：allow（直接执行）/ ask（每次询问）/ deny（拒绝）。

默认策略已经合理：读、搜、列目录直接放行；写文件限制在工作目录内；rm -rf、curl | sh 这类危险命令强制弹卡。同一操作连续重复三次也会触发确认，防死循环烧 token。

三、技能 Skills：沉淀你的套路

技能就是一个带说明的 Markdown 文件，放到技能目录即可被发现：

目录与格式

~/.czagent/skills/          # 全局技能
.czagent/skills/            # 项目技能（跟随工作目录）
└── weekly-report/
    └── SKILL.md

---
name: weekly-report
description: 提到「周报」时用该技能生成周报
---
# 步骤、约束、输出格式……

description 写清楚「什么时候用」——智能体根据这句话自动判断是否加载；
正文随用随加载、回复后释放，不占长期上下文；
「设置 → 技能」里可以全局禁用某个技能；Agent 配置里还能逐条开关。

四、MCP：接入外部工具

配置 .czagent/mcp.json（项目级）或 ~/.czagent/mcp.json（全局），本地 stdio 与远程 HTTP 服务都支持：

mcp.json

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem"]
    },
    "remote-search": {
      "type": "http",
      "url": "https://example.com/mcp/sse"
    }
  }
}

MCP 工具与内置工具同一套权限系统，写操作同样弹卡确认；
单个 server 崩溃不影响会话；Agent 配置里可按 server 三态控制（跟随全局 / 强制开 / 排除）。

五、脚本编排：czagent.ts

对话会话由模型决定做什么；脚本会话由你写代码编排每一步。在工作目录创建入口文件（czagent.ts → czagent.js → .czagent/run.ts 按序探测），新建会话选「脚本」模式，点 ▶ 运行：

每次运行实时读盘重新打包（esbuild → 真实 Node 子进程），改完代码即生效；
npm 第三方包（含 ESM-only）直接 import；
每次工具调用生成消息流卡片，运行过程完全可见、可审计；
占用一个并发槽，可设单次超时（默认不限），点 ■ 随时停止。

ctx API 速查

成员	作用
`ctx.tools.<id>(input)`	直调任意内置工具与 MCP 工具，走权限系统，卡片进消息流
`ctx.agent.run(prompt, opts?)`	委派隔离子代理完成子任务，返回最终文本；可指定 agent / model / 工具白名单 / 步数上限
`ctx.log(...)`	向消息流写日志行（对象自动 JSON 化）
`ctx.use({ mcpServers, skills })`	临时覆盖本脚本可用的 MCP 服务器与技能白名单
`ctx.ask({ tool, args })`	主动弹权限卡征询用户，返回 allow / deny / allowAlways
`ctx.signal`	停止 / 超时中止信号，长循环里应响应
`ctx.settings`	通用设置只读快照（不含 API Key）

示例：代码审查流水线

czagent.ts

export default async function main(ctx) {
  ctx.log('并行审查三个模块…');

  // 三个子代理并行跑，各自隔离上下文
  const targets = ['src/core', 'src/tools', 'src/ui'];
  const reports = await Promise.all(targets.map(dir =>
    ctx.agent.run(
      '审查 ' + dir + ' 的代码，只输出三个最值得修的问题。',
      { tools: ['read', 'grep', 'glob'], maxSteps: 12 }
    )
  ));

  await ctx.tools.write({
    file: 'review-report.md',
    content: reports.join('\n\n---\n\n')
  });
  return { ok: true };
}

脚本运行在真实 Node 子进程（信任级别等同 npm run），不是沙箱：fs、网络、child_process 都可用，请只运行你自己编写的脚本。更多 API 细节见仓库内 docs/tut/脚本编写指南.md。

六、多模态流水线

把 8 类多模态能力串进一条脚本——比如「录音转写 → 提炼要点 → 合成播报音频」：

czagent.ts

export default async function main(ctx) {
  // 1. 语音识别
  const text = await ctx.tools.asr({ file: 'meeting.mp3' });

  // 2. 委派子代理提炼要点
  const summary = await ctx.agent.run(
    '把下面的会议记录提炼成 5 条要点：\n' + text
  );

  // 3. 合成语音播报（八种预置音色可选）
  const mp3 = await ctx.tools.tts({ text: summary, voice: 'anna' });

  ctx.log('完成，音频：', mp3);
  return { summary };
}

图像与视频同理：ctx.tools['image-generate']、ctx.tools['video-generate']（长任务卡片实时显示进度百分比）、ctx.tools['video-from-frame'] 图生视频；语义检索用 ctx.tools.embed + ctx.tools.rerank。生成结果作为富输出直接显示在会话里，脚本拿到的是落盘路径。

七、子代理与任务拆分

对话里：智能体自己会派发 task 子代理并行处理独立子任务（调研、批量改文件），过程以 [agent] 前缀实时回流主会话；
脚本里：用 ctx.agent.run 显式调度，支持 Promise.all 并行（见上例）；
子代理看不到主会话历史，需要背景请写进 prompt 或让它自己读文件；
token 用量计入会话统计；子代理内部不可再嵌套派发。