nami-coding-guide - 编程任务路由与执行指南

本技能是编程任务分流器 + ACPX 任务整理与执行器。一旦识别为编程任务（修 Bug、加功能、重构、代码审查，创建新代码项目等），必须严格遵循以下工作流。

第一阶段：任务分流（简单 vs 复杂）

接收请求后，首先进行二元判断：

简单任务（直接回答，不调 ACPX）
- 特征：生成短片段/正则/SQL/命令、解释代码/报错/API、单文件明确且低风险的小改动。
- 动作：当前模型直接给出高质量结果。
复杂任务（走 ACPX 执行链路）
- 特征：创建多文件新项目/跨文件/跨模块/跨仓库、定位根因、调试复杂 Bug、需要跑命令/构建/测试、或用户明确要求使用 ACPX。
- 动作：进入第二阶段，严禁强行在当前会话中用文本输出大量代码。

第二阶段：复杂任务环境准备与整理（严格按顺序执行）

在调用 ACPX 前，必须严格按照以下两个步骤补齐上下文并建立工作环境。严禁跳过任何一步。

步骤 1：创建并确认工程目录

动态获取实际工作目录：使用 pwd 或 $PWD 获取当前 workspace 路径（通常为 /root/.openclaw/workspace）

如果是新项目：在当前 workspace 下创建项目目录，如：

# 获取实际工作目录
WORKSPACE=$(pwd)  # 通常为 /root/.openclaw/workspace
# 创建项目目录
mkdir -p "$WORKSPACE/<项目名>"
# 示例：mkdir -p /root/.openclaw/workspace/quant-trading-web

如果是已有项目：使用 pwd 确认当前工作目录，或明确指定目标路径。

步骤 2：生成并写入执行任务单

为避免 Shell 转义问题，并在物理路径上锚定上下文，必须将用户需求转换为无歧义的执行任务单，并直接写入$WORKSPACE的目录下（比如文件命名为 $WORKSPACE/xx_yy_project_prompt.txt，其中xx、yy是根据项目名称提取的英文名称）。

请直接执行以下任务，不要进入规划模式，不要询问，一气呵成完成代码编写，完成后汇报结果。

【核心约束】
1. 禁止运行任何阻塞性命令（如 npm run dev/start、vite 等），验证请使用一次性命令（npm run build/test/go build 等）。
2. 遇到编译/类型/运行错误必须尝试自动修复，勿直接交还给人类。
3. 先阅读相关代码再修改；优先最小改动，不做无关重构。

【目标与背景】
<说明具体问题、涉及文件及预期行为>
代码工作目录：已创建"$WORKSPACE/<项目名>" 目录，代码写到这里。

【执行边界】
<允许/禁止修改的模块，必须遵守的架构规范>

【验收标准】
<列出可验证的条件，如：报错消失、构建通过>

第三阶段：调用执行（走 Direct acpx 传话筒模式）

确认ACPX是否安装

查阅acpx技能最新手册：/usr/lib/node_modules/openclaw/extensions/acpx/node_modules/acpx/skills/acpx/SKILL.md
解析命令：查找 acpx 执行程序路径：PATH 环境变量 -> OpenClaw 安装路径 -> 当前仓库 repo-local。

if command -v acpx >/dev/null 2>&1; then
  ACPX_CMD="$(command -v acpx)"
elif [ -x /usr/lib/node_modules/openclaw/extensions/acpx/node_modules/.bin/acpx ]; then
  ACPX_CMD="/usr/lib/node_modules/openclaw/extensions/acpx/node_modules/.bin/acpx"
elif [ -x ./extensions/acpx/node_modules/.bin/acpx ]; then
  ACPX_CMD="./extensions/acpx/node_modules/.bin/acpx"
else
  echo "acpx not found" >&2
  exit 1
fi

# 检查 acpx 版本信息
"$ACPX_CMD" --version

默认优先使用 claude；失败或不可用时，回退至 opencode。

核心执行步骤（后台异步流）

为了直接驱动底层的 Claude Code/Codex/OpenCode 等官方 CLI 代理，我们采用 Direct acpx 路径。严禁依赖可能会导致"假死"或误判的 history 轮询。

请在终端中严格执行以下命令流：

# 0. 准备变量 (执行前务必替换尖括号内的绝对路径和内容)
WORKSPACE=$(pwd)  # 通常为 /root/.openclaw/workspace
CWD_PATH="$WORKSPACE/<项目名>"
SESSION_NAME="oc-claude-task01" # 建议格式: oc-<模型名>-<任务标识>

# 1. 创建或确保目标会话存在 (注意：--cwd 是全局选项，必须放在 claude 前面！)
$ACPX_CMD --cwd "$CWD_PATH" claude sessions show "$SESSION_NAME" || \
$ACPX_CMD --cwd "$CWD_PATH" claude sessions new --name "$SESSION_NAME"

# 2. 提交任务到后台队列 (必须使用 --no-wait 避免主会话阻塞卡死)
# 注意：--cwd 是全局选项放前面，--timeout 1800：30 分钟超时保护 --ttl 0：防止队列因空闲被关闭。 -s 是子命令选项放后面，--format 不是有效选项
$ACPX_CMD --cwd "$CWD_PATH" --timeout 1800 --ttl 0 claude -s "$SESSION_NAME" --no-wait --file "$WORKSPACE/<你的prompt文件.txt>"

# 3. 检查任务状态 (正确格式：全局选项 + agent + 子命令 + 子命令选项)
$ACPX_CMD --cwd "$CWD_PATH" claude status -s "$SESSION_NAME"

⚠️ 会话中止（aborted）问题处理

如果遇到会话被中止（aborted）的情况：

原因分析：
- 主会话阻塞等待时间过长（>60秒无响应）
- 模型 API 超时或网络问题
- 缺少后台执行机制
解决方案：
- 优先使用 --no-wait 模式：启动 ACPX 后立即返回，不阻塞主会话
- 手动轮询检查：使用 exec 定期检查 $ACPX_CMD --cwd "$CWD_PATH" claude status -s "$SESSION_NAME"
- 善后检查：会话中止后，必须主动检查项目状态（构建结果、生成的文件等）并汇报

中止后的必做事项：

# 检查项目目录和构建状态
ls -la /root/.openclaw/workspace/<项目名>/
cd /root/.openclaw/workspace/<项目名> && npm run build

第四阶段：强制汇报与善后（绝对不可跳过）

无论任务成功、失败还是中断，当前模型必须主动执行以下善后流程，绝不能让用户"盲猜"进度！

1. 构建验证与异常处理

成功：使用项目对应命令（npm run build, pytest, cargo build 等）确认验证通过。
失败/中断：必须主动读取错误日志 -> 尝试自动修复（删冗余导入、补类型等） -> 重新构建。若彻底无法修复，整理阻塞原因。

2. 前端项目特殊处理

若为前端 Web 项目（React/Vue/Vite等），在 ACPX 执行并构建成功退出后，当前模型必须自动执行 npm run dev（或对应启动命令），并提取本地访问链接。

3. 标准化格式回传用户

必须按照以下结构向用户输出最终总结：

[✅ 任务完成！ | ⚠️ 任务部分完成 | ❌ 任务遇到问题]

1. 结论：一句话总结执行结果。 2. 根因/现状：Bug 原因或修改前状态。 3. 修改内容：改动了哪些核心文件与逻辑。 4. 验证结果：构建状态（如失败说明尝试过的修复）。 5. 剩余风险/下一步：待解决问题。 🔗 访问链接：<如果是前端项目，附带开发服务器地址>

模型心智防呆清单

我是否错误地把多文件复杂任务直接回答了？（应该交由 ACPX）
我是否在 ACPX prompt 里写入了会导致卡死的 npm run dev？（绝对禁止）
我使用了 --no-wait，但我是否忘记检查任务状态了？（可以稍后用 status 命令查看）
任务报错了，我是不是直接放弃了？（应该主动尝试阅读报错并修复）
任务结束了，我是否遗漏了标准格式的最终汇报？（绝不允许不辞而别）
长时间任务我是否使用了阻塞式等待？（应该用 --no-wait 然后稍后检查）
会话中止后，我是否主动检查了项目状态并汇报？（必须善后）
我是否把 --cwd 放在正确位置了？（必须是全局选项，放在 agent 前面）

Nami Coding Guide

安装技能