最简单的仓颉 Coding Agent

可在指定目录内自主完成开发任务的极简编码智能体。

它能做什么

• 在你指定的工作目录内读写文件、执行命令，完成开发任务
• 通过标准的 OpenAI Chat Completions「函数调用（tool calling）」协议驱动大模型
• 服务商支持：DeepSeek 官方 与 任意 OpenAI 兼容接口（自定义服务）

核心骨架

一个 coding agent 的本质就是一个循环：

用户意图 → 模型思考 → 调用工具 → 观察结果 → 再思考 …… → 最终答复

代码按职责拆成 6 个小文件，每个只讲一件事：

文件	职责
src/main.cj	入口：读命令行 → 解析 → 运行
src/config.cj	配置与命令行解析（服务商、密钥、模型、沙箱目录）
src/sandbox.cj	沙箱：把任意路径安全约束在工作目录内，阻止 ../ 逃逸
src/tools.cj	工具集：read_file / write_file / list_dir / run_command
src/llm.cj	与模型通信：拼请求（messages + tools）、发送、解析工具调用
src/agent.cj	主循环：串起「思考 → 工具 → 观察」直到给出答复

沙箱如何防逃逸

sandbox.cj 用纯词法归一化（不依赖文件是否存在）约束路径：

• 拒绝绝对路径与带盘符的路径；
• 逐段消解 . 与 ..，任何越过根目录的 .. 都直接拒绝。

于是 ../../etc/passwd、/etc/passwd 这类路径在触碰文件系统之前就被拦下。

工具调用循环

agent.cj 的 handleTurn 每轮请求模型：

• 模型返回 tool_calls → 逐个执行工具、把结果作为 role=tool 消息回灌，继续下一轮；
• 模型返回纯文本 → 视为最终答复，本轮结束。

以 maxSteps 兜底，避免死循环。

构建

依赖仓颉 stdx 扩展库（net.http / net.tls / encoding.json）。 cjpm.toml 已按 Windows 目标配好二进制依赖路径（指向随附的 stdx 动态库），直接：

cjpm build

产物在 target/release/bin/main.exe。独立运行需保证 stdx 动态库在库搜索路径中 （用 cjpm run 则自动处理）。

使用

cjagent [选项] [工作目录]

  工作目录            Agent 可读写的沙箱根目录（默认当前目录），不会逃逸到其外层

选项:
  --provider <名称>   deepseek（默认）| openai（OpenAI 兼容自定义服务）
  --base-url <URL>    服务基址；openai 必填，deepseek 默认 https://api.deepseek.com
  --api-key <KEY>     API 密钥；或用环境变量 DEEPSEEK_API_KEY / OPENAI_API_KEY
  --model <名称>      模型名（默认 deepseek-v4-pro）
  --task <描述>       直接执行一次性任务；省略则进入交互式对话
  --max-steps <N>     单轮最多工具调用轮数（默认 25）
  -h, --help          显示本帮助

示例

一次性任务（DeepSeek 官方）：

main.exe --api-key sk-xxxx --task "创建 fib.py 打印前 10 个斐波那契数并运行验证" ./workspace

交互式对话：

main.exe --api-key sk-xxxx ./workspace

对接自定义 OpenAI 兼容服务（如本地推理服务）：

main.exe --provider openai --base-url http://localhost:11434/v1 --model qwen2.5-coder --api-key x ./workspace