模块 `code` — 代码库操作

🟢 该模块让代理能够访问项目代码：读取、创建和精确编辑文件，浏览/搜索，运行命令（构建、测试、git）。附带一个现成的代理 coder。该模块是 双传输（dual-transport）：同一份代码既可作为 linked crate 使用，也可作为原生 DLL 使用。

提供内容

内容	标识符	描述
工具	`kind: read_file` … `run_command`	对项目代码的 6 种操作
代理	`coder`	已接入工具的现成代码代理
配置	`code/code_root`	项目根目录（映射到 `AGENT_OS_CODE_ROOT`）

该模块包含在默认集合中（server.yaml → modules.enabled）。

工具

`kind`	用途
`read_file`	读取文件/行范围
`write_file`	创建新文件（仅创建）
`edit_file`	精确替换片段（`old_string` → `new_string`）
`list_files`	按 glob 列出文件
`grep`	按内容搜索（regex）
`run_command`	在项目根目录运行命令

list_files/grep 不会进入 .git 以及 vendor/缓存目录（node_modules、 target、.venv、.next 等），并限制遍历（FS_MAX_SCAN），因此在大目录树上搜索不会挂起流程。

工具不直接触碰文件系统和进程——它们通过 host 端口 agent_os.Fs 和 agent_os.Process 进行访问，因此内核沙箱在两种传输中同样适用，并且该模块会声明相应的 capabilities。

项目根目录

优先级：

工具 YAML 中的 root:（绝对路径或带 ${VAR}）；
调用上下文中的 template_vars[code_root] —— 这样目录会通过 subagent_tool 的 params 传递给子代理 （键由字段 root_var 配置）；
AGENT_OS_CODE_ROOT（设置页面上的 code/code_root 配置）；
服务器的工作目录。

所有路径均相对于根目录；绝对路径和 .. 会被拒绝；禁止越出根目录（包括通过符号链接）。此外还会应用代理沙箱（read_roots/write_roots）。

编辑——仅限精确编辑

edit_file 替换唯一的片段；不会整体重写文件。 write_file —— 仅创建（不会覆盖已存在的文件）。

`run_command` 与安全

命令由 LLM 选择。策略位于工具 YAML 中：

deny:  [rm, sudo, shutdown]   # запрещённые программы/строки
# allow: [cargo, git, npm]    # если задан — разрешены только перечисленные
approval:                     # gate одобрения человека (ядро)
  required: true
  severity: high
  timeout_secs: 600
  on_timeout: deny
  action: "Выполнить команду: {{ input.command }}{% if input.args %} {{ input.args | join(' ') }}{% endif %}?"

外加硬性超时；在 linked 构建中——内核沙箱限制（CPU/mem/procs/ fsize，杀死进程树）。在 DLL 构建中不应用内核限制—— 防护仅限于 approval + 策略 + 超时。

代理 `coder`

以 config 捆绑包（agents/coder/）形式提供，并在模块启用时与 config/agents/ 一同加载。为全部六个工具声明 tool_files。代理 config/agents/coder（如果存在）优先于捆绑包中的代理。

coder 由 admin_only: true 声明：只有管理员（admin 令牌或 admin 登录 cookie）才能与其交互，普通用户和匿名用户会收到 403。这保护了强大的工具（编辑文件、运行命令）。在关闭身份验证时该门禁是开放的——请设置 server.yaml → auth。

模块如何贡献

该模块为 tool.engines 注册表中的每个 kind 提供一个 stable 对象 ToolEngine，并声明 capabilities：

agent_os_sdk::declare_module!(
    CodeModule, "code", contribute, DOCS,
    capabilities = ["agent_os.Fs", "agent_os.Process"]
);

模块 code — 代码库操作