与 Coding Agent 协作

Cell 的设计目标之一，是让 coding agent（Claude Code、Codex、Cursor、CodeBuddy、pi……）第一次就用对：每件事只有一种写法，错误带结构化的修复建议，命令输出可供机器读取，文档与已安装的版本一致。本页写给配置 agent 的人；agent 自己读的指南是 AGENTS.md。

项目里有什么

cell init 会写入下列文件；升级 Cell 或增加组件后，npx cell agent sync 重写其中由 Cell 管理的部分：

文件	用途
AGENTS.md	已安装的 @celljs/cli 版本的 Cell 指南，后面是已安装组件的指南片段。Cell 只重写 <!-- cell:begin --> 和 <!-- cell:end --> 之间的内容；项目自己的规则写在外面
CLAUDE.md	@AGENTS.md，给 Claude Code
.agents/skills/cell/SKILL.md	同一份指南，以 agent skill 的形式提供
.mcp.json	启动 npx cell mcp

把 npx cell agent sync 加进升级流程，或放进 postinstall 脚本。

MCP

npx cell mcp 是项目的 stdio MCP 服务器，工具返回与对应命令相同的 JSON：

工具	命令	副作用
info	cell info	无
check	cell check	无
config_get	cell config get	无
docs_search	cell docs	无
build	cell build	写输出目录
deploy_plan	cell deploy --dry-run	写输出目录；可能联网

有意不提供部署工具：部署由人执行 cell deploy。

// .mcp.json（Claude Code、Cursor、CodeBuddy）或 .cursor/mcp.json
{ "mcpServers": { "cell": { "command": "npx", "args": ["cell", "mcp"] } } }

# Codex：~/.codex/config.toml
[mcp_servers.cell]
command = "npx"
args = ["cell", "mcp"]

cell dev 运行时，http://127.0.0.1:<port>/_cell/mcp 是运行中应用的第二个 MCP 服务器（HTTP）：get_errors、list_routes、list_bindings、get_config、recent_requests 和 logs。它只接受本机的请求。

agent 常用的命令

命令	得到
npx cell check --json	所有类型、配置、装饰器和 DI 问题，带 code、file、line 和 hint
npx cell info --json	preset、组件、DI 模块、入口、hooks、产物状态
npx cell config get <key> --why	合并后的配置值，以及每一层的来源
npx cell docs <关键词>	已安装的包随包发布的文档中的段落（各包 README、这些指南和 CLI 文档）
npx cell build --json、npx cell deploy --dry-run --json	一行结果，而不是进度输出

每个命令都接受 --json（stdout 上一个带 schemaVersion 的 JSON 文档，其余都走 stderr），不在终端里时从不提问，有副作用的命令都有 --dry-run。退出码：成功 0，失败 1，用法错误 2。

错误

工具链和运行时的每个错误都有固定的错误码、错误信息、一句话的修复建议和文档链接：

[CELL_DI_NO_BINDING] No binding for Symbol(Mailer), needed by Signup.mailer (TodoController → Signup → Symbol(Mailer)).
  fix: Bind the identifier in a DI module (@Component(<id>) in a file the module imports), or mark the injection @Optional().
  docs: https://cell.cellbang.com/errors/cell-di-no-binding

错误码列表为每个错误码提供一个页面。错误码和 --json 字段在 4.x 内保持稳定。

给模型读的文档

文档站发布了 llms.txt（全部页面的索引）和 llms-full.txt（指南、CLI 文档和各包文档合成一个文件），中文版在 /zh/llms.txt 和 /zh/llms-full.txt，供从网上读文档的 agent 使用。在项目里则优先用 cell docs：它检索的是你安装的版本。

行之有效的习惯

• 让 agent 每次改动后都运行 npx cell check 和测试；两者都快，输出也是为它设计的。
• 项目规则写在 AGENTS.md 中 Cell 标记之外。
• 让 agent 随意使用 cell deploy --dry-run；cell deploy 本身及其所需的凭据留给人。