new-agent

为 Boring 应用添加一项能力

应用是能力提供方（hachej/boring-app）。每个能力文件夹都是可选的；boring.json 声明中心可以使用哪些能力。**添加定义；只有当中心必须能够调用它时，才将其添加到 boring.json 中。**未声明的定义属于内部定义：它在应用内部可用，但不会出现在清单中。

选择能力类型

需求	创建	在 boring.json exposes 中声明
一次具有契约的模型调用	agents/<name>/agent.md（+ rules.md、tool.json）	如果中心会调用它，则声明 agents.<name>: "<one line>"
多个具有生命周期的 Agent（由多个部分生成结果）	agents/<name>/JOB.md + index.mjs（plan、collect）	jobs.<name>
在一个 Agent 上保留历史记录的对话	agents/<name>/CHAT.md（+ 可选的 index.mjs context）	chats.<name>
Agent 或中心调用的纯函数	tools/<name>/tool.json（runtime: sandbox）+ tools/<name>/index.js	tools.<name>: { runtime, description }
需要数据库、网络或密钥的函数	tools/<name>/tool.json（runtime: server）+ server/src/tools/<name>.ts	tools.<name>
绑定数据、可由中心呈现的组件	web/src/views/<name>/index.tsx（+ 在 web/src/main.tsx 中注册）	views.<name>: { shows, description }
应用自身的屏幕	web/src/pages/<name>/index.tsx	pages.<name>

大多数功能只需一个 Agent 即可。只有在功能需要协调多个 Agent 并具有生命周期时才添加作业；只有在人们需要多轮与 Agent 对话时才添加聊天。agents/ 中的名称必须全局唯一。

一个 Agent

agents/<name>/
  agent.md     front matter + system prompt (the body)
  rules.md     the owner's rules, read-only in Settings; they change by pull request
  tool.json    only when output: tool: { name, description, input: JSON schema } (the output schema)
  index.mjs    optional: buildMessage(input), validate(output), asText(output); then the agent needs server/

agent.md 前置元数据：name（文件夹名称）、title、description、model（openai-codex/<model>）、effort、max_tokens、output（tool 或 markdown）、helper_tools: [<tool names>]（只能使用已声明的工具）、inputs:（name: { type, description, required }）。

• 声明式（没有 index.mjs）：消息由规则和输入组成；markdown 输出不得为空，工具输出必须包含 tool.json 中的必填字段。中心仅凭文件就能运行它。
• 包含代码：在存储任何内容之前，运行时会通过 validate(output) 应用契约（APP-B4）；使用 agents/_shared/validate.mjs 中的 fail("…") 拒绝，并向模型提供说明消息。
• 假模型（server/src/fake-models.ts）会响应 markdown Agent；对于工具 Agent，请添加脚本化回复，否则其测试无法运行。
• Cloudflare 应用（project.md 中的 runtime: cloudflare）不会运行 Agent 运行时：其 Agent 保持声明式，由中心运行。Agent 或聊天中不得包含 index.mjs，也不得包含作业；verify check 会拒绝它们。

一个工具

• 沙箱：tools/<name>/index.js 定义 function run(input, ops)，使用纯 JavaScript，不得导入模块、使用 Node 或网络 API，且只能使用 tool.json 在 operations 下列出的 ops.<name>。verify check 会拒绝其他内容。
• 服务端：server/src/tools/<name>.ts 导出 handler(input, { db })；使用 zod 验证输入，并对每个查询都使用 await（相同代码同时运行于 SQLite 和 D1）。在 Cloudflare 应用中不得使用 Node API（遵守 worker-portable 规则）。
• tool.json：包含 description、runtime、input 和 output JSON 架构。

数据、路由和 Web

• 数据表：修改 server/src/db/schema.ts，然后运行 npm run db:generate，并提交 server/drizzle/（绝不要运行 drizzle-kit push）。写入操作会编辑数据时，须注明其读取的版本（APP-B3；server/src/routes/memories.ts 是示例）。
• 路由：server/src/routes/<name>.ts（Hono + zValidator），并在 server/src/app.ts 中挂载。
• Web 只能通过 web/src/lib/api.ts 访问服务端（web/src/lib/model.ts 存放调用）。

测试与验证

1. 单元测试（npm test）：通过应用测试路由和工具 （test/unit/app.test.mjs），以及 Agent 在包含代码时的契约。
2. 当用户看到新内容时，进行端到端测试（test/e2e/journey.spec.mjs）。
3. 运行 node scripts/verify.mjs check，然后使用 verify-app 技能驱动验证。
4. 功能地图：docs/verify/ 中对应区域的文件，说明用户可以执行哪些操作。

切勿

• 意外暴露内容：要么显式声明，要么保持内部状态。
• 在运行时之外调用模型，也不要向沙箱工具传入导入内容。
• 编辑 vendor/。