智能体 CLI 编程能力

一套面向智能体的代码编辑工具包。提供 oce 命令，将读取、搜索、编辑、验证、格式化、备份及多文件事务等操作封装在一个可预测的统一接口中——该接口在每次写入后自动执行语法验证，并在验证失败时自动回滚。

本能力存在的原因在于：原始的 sed、awk 和 perl -i 对自主运行而言过于危险——它们静默应用变更、正则匹配易产生误报、不保留审计痕迹，且无法回滚。oce 在保留命令行编辑速度的同时，增加了智能体所需的“安全护栏”。

调用方式 —— oce 简写语法

本文档中为便于阅读，统一使用 oce <子命令> 形式。实际调用方式如下之一：

# 方式 A —— 直接调用（无需配置，立即生效）：
bash /scripts/oce.sh <子命令> [参数]

# 方式 B —— 为当前会话创建一次性别名（推荐智能体使用）：
alias oce="bash /scripts/oce.sh"

# 方式 C —— 将封装脚本安装至 PATH（持久生效）：
bash /scripts/install.sh

对智能体场景，建议在任一涉及编辑操作的会话起始处一次性设置别名，此后该会话内所有操作均使用 oce <子命令>。请将 替换为该能力的实际安装路径（通常类似 /home/agent/.skills/agentic_cli_coding）。

环境验证

完成别名设置（或安装）后，在任意编辑会话开始前执行一次：

oce doctor

若返回退出码 0 且输出 Setup OK，表示工具包已就绪。“核心工具”（node、patch、diff、grep、acorn）必须全部存在；缺失可选工具（如 prettier、gofmt 等）仅影响对应语言的格式化功能，不影响编辑本身。

若提示 oce: command not found，说明别名未成功设置，或安装的封装脚本未加入 PATH。此时请改用方式 A（直接调用）。

方法论 —— 如何系统性处理任意代码任务

若用户任务简单，可直接跳至对应步骤。对于非平凡任务，请严格按以下四步执行。

1. 定位 —— 理解项目结构

编辑前，务必明确你要修改的对象。

oce tree --depth 2                  # 当前项目包含哪些内容？
oce find "<关键词>" --type   # 相关代码位于何处？
oce ast symbols path/to/file.js     # 该文件定义了哪些函数/类？

切勿因“训练中已知答案”而跳过定位步骤。不同仓库的约定差异巨大，想当然正是智能体破坏代码库的根源。

2. 阅读 —— 加载你真正需要的上下文

oce read src/server.js --around "handleAuth" --context 20
oce grep-context "TODO" src/server.js -c 5
oce read src/auth.js --lines 45:120

需读取足够多的周边上下文，以准确预判你的修改将产生何种影响。最廉价的破环方式，就是孤立地编辑某个函数而无视其调用者。

3. 规划 —— 动手前先书面明确修改方案

对非平凡编辑，必须在执行前显式陈述完整计划：

• 新增内容（新行、新文件）
• 移除内容（删除、弃用）
• 修改内容（原地变更）
• 风险点（涉及相同符号的文件、公开 API、测试用例）
• 验证项（哪些文件需通过编译、哪些测试应继续通过）

若修改跨多个文件，请在首次编辑前启动事务：

TXN=$(oce transaction begin)

随后对每个后续的 oce replace、oce insert、oce delete、oce write、oce patch 或 oce ast 命令，均传入 --txn "$TXN" 参数。最终可选择提交（原子化验证全部变更）或回滚（还原所有文件）。

4. 执行 —— 选用合适编辑工具并验证结果

决策流程如下：

是否需要修改代码？
├── 微小、精准、字面量替换         → oce replace
├── 在已知锚点插入新代码           → oce insert --before-match | --after-match | --line
├── 删除特定行或匹配行             → oce delete --lines | --match
├── 基于上下文的多行精确变更       → oce patch apply  （编写 unified diff）
├── 全局重命名 JS/JSX 标识符       → oce ast rename
├── 替换整个函数/类主体            → oce ast replace-symbol
├── 创建全新文件或全量重写         → oce write
└── 跨多文件的协同变更             → oce transaction + 上述任意命令

每次编辑后，工具包会自动校验目标文件语法，并在语法错误时自动回滚。你无需手动重新验证，但应执行 oce diff <文件> 确认变更符合预期。

决策树 —— 各类任务对应命令速查

发现（DISCOVERY）                    阅读（READING）
────────────────                     ────────────────
项目结构？           tree           完整文件？         read <文件>
某内容位于何处？     find           特定行范围？       read <文件> --lines A:B
函数/类列表？        ast symbols    某位置周边上下文？ read <文件> --around X -c N
带上下文的匹配？     grep-context   匹配并附带上下文？ grep-context X 文件 -c N

编辑（小型变更）                      编辑（大型/结构性变更）
────────────────                     ────────────────
精确字符串替换       replace        全文件重写              write
在锚点插入代码       insert         应用 unified diff       patch apply
删除行或匹配行       delete         JS/JSX 标识符全局重命名   ast rename
                                     替换函数/类主体         ast replace-symbol

验证与恢复（VERIFY & RECOVER）
────────────────
语法检查              validate       （每次编辑后自动运行）
标准格式化            format         （手动触发）
查看最近变更          diff           （对比上一份备份）
列出备份              backup list
恢复备份              backup restore <文件> [--at N]

多文件原子操作（MULTI-FILE ATOMIC）
────────────────
TXN=$(oce transaction begin)
oce <编辑命令> ... --txn "$TXN"   （重复执行）
oce transaction validate "$TXN"
oce transaction commit "$TXN"   |   oce transaction rollback "$TXN"

标准工作流

修改现有函数（单文件）

oce find "function processRequest" --type js
oce read src/server.js --around "processRequest" --context 15
oce replace src/server.js 
  --old "return data;" 
  --new "return sanitize(data);"
oce diff src/server.js

在已知锚点添加新代码块

oce find "// END ROUTES" src/server.js
cat > /tmp/new_route.js <<'EOF'
app.get('/health', (req, res) => res.json({ ok: true }));
EOF
oce insert src/server.js --before-match "// END ROUTES" --content-file /tmp/new_route.js

跨文件重命名 / 重构

TXN=$(oce transaction begin)
oce replace src/auth.js --old "validateToken" --new "verifyToken" --all --txn "$TXN"
oce replace src/api.js  --old "validateToken" --new "verifyToken" --all --txn "$TXN"
oce replace tests/auth.test.js --old "validateToken" --new "verifyToken" --all --txn "$TXN"
oce transaction validate "$TXN"
oce transaction commit "$TXN"   # 若发现异常则改用 rollback

对于纯 JS/JSX 场景，优先使用 oce ast rename —— 它遍历 AST，仅重命名真实的标识符引用，不会误改字符串或注释中的文字。

精确的多行补丁

当需要完全控制多行变更时，可编写 unified diff：

cat > /tmp/fix.patch <<'EOF'
--- a/src/auth.js
+++ b/src/auth.js
@@ -12,6 +12,10 @@
 function authenticate(req) {
+  if (!req.headers.authorization) {
+    throw new Error('Missing auth header');
+  }
   const token = req.headers.authorization.split(' ')[1];
EOF

oce patch apply /tmp/fix.patch

补丁首先进行试运行校验；若无法干净应用，则命令会在任何文件被修改前即失败。应用后，每个受影响文件均会被语法验证，且只要任一文件语法出错，整个补丁即自动回滚。

从错误编辑中恢复

oce backup list <文件>           # 查看可用快照
oce backup diff <文件>           # 对比当前与最新备份
oce backup restore <文件>        # 恢复最新备份
oce backup restore <文件> --at 3 # 恢复倒数第 4 份备份（索引从 0 开始）

所有破坏性操作前均自动创建备份。备份存于工作区内的 .oce/backups/ 目录下。

反模式 —— 绝对禁止的操作

这些是智能体最容易踩坑的失败模式，请务必内化。

禁止使用 sed -i、重定向到同一文件的 awk 或 perl -i 进行编辑。 它们不提供任何验证、无备份机制，且正则匹配失败时会静默部分成功。请改用 oce replace（字面量匹配）或 oce patch（精确控制）。

禁止使用 oce write 进行微小编辑。 write 会完全替换整个文件。若仅需修改三行，请使用 replace、patch 或 insert。全量重写仅适用于新建文件，或你已程序化加载并修改了整个文件内容的场景。

禁止在未指定 --all 的情况下，向 oce replace 传入非唯一 --old 字符串。 此时命令将因“匹配不明确”而失败——这是设计使然。请要么增强 --old 的特异性（例如加入缩进或右大括号等上下文），要么确需全局替换时传入 --all。

禁止对单个逻辑变更涉及的多个文件，不启用事务即直接编辑。 若文件 2 的编辑验证失败，文件 1 将处于不一致状态。transaction begin + --txn + commit/rollback 可确保所有操作原子化。

禁止在非平凡编辑后跳过 oce diff。 仅需一条命令即可确认变更是否符合你的思维模型。自动验证仅能捕获语法错误，无法识别逻辑错误。

禁止假设格式化器已运行。 oce format 仅在对应格式化器已安装时才生效。如需确认，请检查 oce doctor 输出。

禁止编辑二进制文件。 oce 默认拒绝；若你发现自己试图调整 OCE_MAX_FILE_SIZE 或绕过二进制检测，请立即停止并重新评估。

禁止臆造文件路径。 编辑前务必通过 oce read 或 oce tree 确认文件真实存在。工具包对缺失文件会报错，但更佳实践是主动检查。

输出格式 —— --json 用于程序化解析

所有命令均支持 --json 参数，将在 stdout（或 stderr，若发生错误）输出单行 JSON 对象。适用于命令链式调用或结果解析。

快速参考（完整 Schema 见 references/json-schema.md）：

// 成功
{"status":"success", "file":"src/x.js", "replacements":3, "backup":"/path/to/backup"}

// 错误
{"status":"error", "message":"Found 5 matches; pass --all or make --old more unique"}

// 试运行
{"status":"dry_run", "file":"src/x.js", "matches":3, "message":"would replace 3 occurrence(s)"}

// 验证
{"status":"success", "file":"src/x.js", "language":"javascript", "validator":"node --check", "valid":true, "output":""}

对存在歧义的结果（如 find 返回大量匹配、ast symbols），JSON 中将包含 matches 或 symbols 数组。

全局参数

以下参数适用于所有命令：

语言支持概览

oce 支持并可安全编辑以下语言的文件：JavaScript（.js .mjs .cjs .jsx）、TypeScript（.ts .tsx）、Vue（.vue）、Svelte（.svelte）、Python（.py）、Ruby（.rb）、Go（.go）、Rust（.rs）、Java（.java）、Kotlin（.kt）、Swift（.swift）、C/C++（.c .h .cpp .hpp）、C#（.cs）、PHP（.php）、Bash/Zsh（.sh .bash .zsh）、JSON、YAML、TOML、XML、HTML、CSS/SCSS/LESS、Markdown、SQL、Dockerfile、Makefile。

验证深度取决于本地已安装工具。完整支持矩阵见 references/language-support.md。

AST 级操作（oce ast）原生支持 JS/JSX（由 acorn 直接解析）。对 TypeScript 文件，AST 命令仅支持 JS 兼容子集；如需完整 TS 支持，请在本地安装 tsc。其他语言请使用基于文本的编辑（replace、patch）。

存储与状态

该能力不会向你的家目录写入任何内容。所有状态均保存在当前工作目录下的 .oce/ 目录中：

<项目>/.oce/
├── backups/         每次破坏性编辑前的文件快照
├── transactions/    活跃及历史事务记录
└── edit.log         每次编辑的审计日志

你可安全地将 .oce/ 加入 .gitignore。清理时，执行 oce backup clean [DAYS] 可删除早于 DAYS 天（默认 30 天）的备份。

参考文档

如需深入查阅，请按需阅读以下资料：

• references/json-schema.md —— 所有命令的精确 JSON 输出 Schema。在链式调用或程序化解析输出时必读。
• references/workflows.md —— 更长的实操示例：缺陷修复流程、功能添加流程、重构流程、依赖升级流程、Vue/React 组件编辑流程。
• references/language-support.md —— 按语言划分的验证器与格式化器支持矩阵；明确哪些功能开箱即用，哪些需项目级工具链支持。
• references/troubleshooting.md —— 实战中常见故障现象 → 根本原因 → 解决方案的对照表。

一句话总结

oce <动词> <文件> [选项] —— 每个动词均在操作前自动备份、操作后自动验证，并在语法错误时自动回滚。跨文件变更请使用事务。先阅读，再编辑；先规划，再执行。