# Cell 4 第一原则：Coding Agent 优先

状态：设计记录（2026-11-07 起草；4.0.0 已按本文实现，未实现的条目标注"未实现"）。不是用户文档，用法见 [CLI 参考](../../dev-packages/cli/README.md)。**这是 Cell 4 最高优先级的设计原则**：除正确性和安全外，其他设计目标与它冲突时，以它为准。[architecture.md](./architecture.md) 和 [modules.md](./modules.md) 都按本文约束。

## 1. 目标

Cell 应用的大部分代码将由 coding agent（Claude Code、Codex、Cursor、pi、CodeBuddy 等）编写和维护，人负责审阅和决策。Cell 要让 agent：

1. **一次写对**：只有一种写法，约定显式，错误在编译期或 `cell check` 里就暴露。
2. **少花上下文**：需要的信息能精确取到，输出简短、结构化，不用读整个仓库或刷屏的日志。
3. **自己闭环**：改完代码后自己验证、自己定位问题，不需要人看终端。
4. **安全地自主行动**：有副作用的操作先给出计划，不弹交互，不泄露凭据。

衡量方式：仓库内维护一组 agent 任务评测（§5），以成功率、轮次、token 消耗作为指标，回归时阻止发布。

## 2. 设计规则

| # | 规则 | 具体要求 |
|---|---|---|
| R1 | **一种写法** | 同一件事只有一种写法：模块是工厂函数、开关是 `modules` 里的 `!`、插值是 `${}`、应用配置写 `cell.yml`、工具链配置写 `cell.config.ts`。新增 API 前先问"能不能用已有的写法表达" |
| R2 | **显式、可 grep、生成物落盘** | 约定只用于减少样板，且都能被 `cell info` 列出来。构建时生成的代码（DI 装配、合并后的配置、入口）同时写到 `.cell/generated/`，agent 可以直接读到"容器里到底装了什么" |
| R3 | **类型即文档** | `cell.config.ts` 全量类型；组件为自己的配置项提供 schema，合成 `.cell/schema/cell.yml.json` 供编辑器与 agent 校验（未实现）；配置键生成类型（`.cell/types/config.d.ts`），`@Value('cell.server.port')` 写错键直接编译报错（未实现）；前后端 RPC 共享类型 |
| R4 | **快速、确定的反馈** | `cell check` 一条命令完成类型检查、配置 schema、装饰器元数据、DI 绑定可解析性检查，增量运行目标 5 秒内；同样的输入永远得到同样的输出 |
| R5 | **结构化错误** | 所有错误都是 `CellError { code, message, file?, line?, hint, docs }`。`code` 稳定（如 `CELL_DI_NO_BINDING`），`hint` 是一句可执行的修复建议，`docs` 指向该错误的固定文档页。运行时 DI 错误要写清"谁需要什么、在哪个文件、当前有哪些候选绑定"，不直接抛 inversify 的原始信息 |
| R6 | **上下文经济** | 默认输出简短；所有命令支持 `--json`（带 `schemaVersion`）；长输出截断并给出完整内容所在文件；日志写入 `.cell/logs/*.ndjson`，可按时间和级别查询（未实现） |
| R7 | **版本匹配的知识** | 每个组件包随 npm 发布 `docs/` 和一段 `AGENTS.md` 指南片段。`cell agent sync` 根据已安装组件及其版本，生成项目的 `AGENTS.md` 和 `.agents/skills/cell/`，agent 读到的永远是当前版本的用法（借鉴 Next.js 随包文档、Laravel Boost 按版本生成指南） |
| R8 | **可内省的运行中应用** | `cell dev` 在 `/_cell/mcp` 暴露 MCP 端点：`get_errors`、`list_routes`、`list_bindings`、`get_config`、`recent_requests`、`logs`；`cell mcp`（stdio）暴露项目级工具：`info`、`check`、`config_get`、`docs_search`、`build`、`deploy_plan`。每个工具标注只读/有副作用、是否联网（借鉴 Angular CLI），`deploy_apply` 默认不暴露 |
| R9 | **安全的自主** | 非 TTY 或检测到 agent 环境时从不提示输入；有副作用的命令都有 `--dry-run`；部署分 `plan` / `apply`；破坏性操作必须显式 `--yes`；凭据只来自环境变量或 `cell login`（未实现），所有输出与日志自动脱敏 |
| R10 | **局部性** | 一个功能尽量落在一个目录：控制器、服务、模块注册、该功能的配置默认值放在一起；模块是一个文件；一个组件的全部声明在它的 `package.json` 的 `cell` 字段里 |
| R11 | **可在内存中测试** | `createTestApp()` 在进程内启动完整 DI 容器与 HTTP 处理链，不监听端口；agent 写集成测试只需几行，`bun test` 秒级完成 |
| R12 | **稳定契约** | 错误码、`--json` 输出结构、MCP 工具名在 4.x 内保持稳定；变更走 `schemaVersion` |

## 3. 落到各模块的要求

| 模块 | 要求 |
|---|---|
| `@celljs/vite` | 项目模型（组件图、mode、各 target 的 DI 模块、入口、合并后的配置及每个值的来源）以纯数据对象提供，可直接 JSON 序列化；生成代码同时写入 `.cell/generated/`；所有失败抛 `CellError` |
| `@celljs/cli` | 每个命令 `--json`；`info`、`check`、`config get --why`、`docs`、`explain <code>`、`mcp`、`agent sync`；非交互默认 |
| `@celljs/kit` | `addConfigSchema`、`addCheck`、`addMcpTool`、`addDocs`；模块注册的一切出现在 `cell info --json` 中并标明来源 |
| 运行时（core / web / mvc） | DI 错误改写（R5）；`createTestApp()`；开发期把未捕获错误与请求记录交给 dev MCP 端点 |
| 部署器 | `plan` 输出结构化差异；凭据脱敏 |
| 模板 | 自带 `AGENTS.md`、`.agents/skills/cell/SKILL.md`、MCP 配置示例（Claude Code / Codex / Cursor / pi / CodeBuddy） |
| 文档站 | `llms.txt`、`llms-full.txt`；每个错误码一页（未实现） |

## 4. 因此而改变的设计

- 组件发现只读 `package.json`、不执行代码：`cell info` 和 MCP 工具可以秒级返回。
- 虚拟模块不再只存在于内存，同时落盘到 `.cell/generated/`。
- 不提供"多种等价写法"的便利（例如不支持把应用配置写进 `cell.config.ts`）。
- 开发服务器、构建、部署全部有结构化事件流，CLI 的人类可读输出只是这个事件流的一种渲染。
- 实施顺序调整：项目模型、结构化错误在 P1；`--json`、`info`、`check`、MCP 在 P2，不再放到最后。

## 5. Agent 评测

仓库的 `evals/`（运行方式见 [evals/README.md](../../evals/README.md)）：每个任务是"起始项目 + 自然语言需求 + 验收脚本"，用 headless 的 coding agent 执行，统计成功率、轮次与 token。首批任务：

1. 新增一个带参数校验的 REST 接口并写测试。
2. 接入 typeorm，新增实体与增删改查接口。
3. 修复一个 DI 绑定缺失的报错（只给错误输出）。
4. 给前端页面加一个调用后端 RPC 的组件。
5. 把应用改为部署到 FC，并给出 `deploy --dry-run` 计划。
6. 写一个本地模块：构建后把产物清单上报到指定 URL。

每次发布前跑评测；结构化错误、文档片段、MCP 工具的改动都以评测结果为依据。

## 6. 参考

| 来源 | 借鉴点 |
|---|---|
| Next.js 16+ | 开发服务器内置 MCP 端点（`get_errors` 等）；随项目分发、与版本匹配的文档 |
| Laravel Boost | 按已安装包及版本生成 agent 指南；MCP 工具（应用信息、日志、文档检索） |
| Angular CLI | `ng mcp`；工具标注只读与仅本地；最佳实践作为工具提供 |
| pi | 文档面向 agent 书写；扩展 API 小而一致 |
| Agent Skills（`SKILL.md`） | 以技能目录分发框架用法，多种 agent 通用 |