在 LoopX 中使用 KunlunCode

接入后得到什么

KunlunCode 是 LoopX 的一等 host surface。LoopX 保存 goal、todo、claim、quota、边界和 writeback；KunlunCode app-server 运行原生 Goal continuation 与 Goal Pro 独立 verifier。

三套命令空间：并不完全一致

接入后同时存在 LoopX shell CLI、KunlunCode TUI slash 和 LoopX MCP tools。名称相似不代表状态相通，也不存在自动的一一映射。

从产品语义看，/goal-pro 就是普通 native Goal 加强制独立验证。协议中普通 Goal 对应 arrangement，Goal Pro 对应 strict；Strict 还约束协调/委派方式，但真正决定完成的是 verifier gate。它仍是 KunlunCode 原生状态，不是 LoopX goal 的高级版。

/goal [status|history|pause|resume|clear|edit [--budget <tokens>] <objective>
      |--budget <tokens> <objective>|<objective>]

/goal-pro [status|history|pause|resume|clear|edit [--budget <tokens>] <objective>
          |[--answer] [--budget <tokens>] [--] <objective>]

原生 Goal 由谁激活

/goal 由 KunlunCode TUI 解析，并不是模型能够输入给自己的普通文本命令。除人工 slash 命令外，本机版本还提供受约束的模型工具和 app-server 路径。

只有 Goal 被激活后，KunlunCode runtime 才会注入 continuation 指令并驱动后续 Goal turns。普通 headless prompt 不会因为任务看起来很长就自动进入 native Goal。

当前适配器组合两个循环

loopx-kunluncode run 不伪造 slash 文本，也不等待模型自行决定是否调用 create_goal。它直接创建或恢复 thread，调用 thread/goal/set 与 turn/start，让 KunlunCode 自动续跑；本地 journal 负责进程中断后的恢复和 writeback 对账。

• LoopX 管理 + 原生严格长任务：默认 --mode goal-pro。
• 普通 native Goal：使用 --mode goal；旧单轮 MCP worker：使用 --mode headless。
• 只使用 KunlunCode 自己的持久目标：使用 /goal 或 /goal-pro，但不要把其状态当作 LoopX writeback。
• /mcp 只查看 KunlunCode 已加载的 MCP 工具，不会把 LoopX CLI 变成 slash 命令。

前置条件

• 主机上的 kunluncode 已安装并能启动 provider；
• uv 与 Git 可用；
• 拥有包含 KunlunCode 适配器的 LoopX 发布包，或用于开发的源码 checkout；
• 拥有目标项目目录；若安装 MCP/使用 legacy headless，还需用户 MCP 配置写权限。

python3 --version
kunluncode --version
uv --version
git --version

export LOOPX_KUNLUN=loopx-kunluncode
export TARGET_PROJECT=/path/to/your-project
export LOOPX_GOAL_ID=my-long-running-goal
export KUNLUN_AGENT_ID=kunlun

安装适配器

普通用户安装发布包；install 会通过 uv 创建 adapter-owned MCP 环境，安装相同版本的 LoopX 与 mcp==1.28.1，不要求源码 checkout。

python3 -m pip install --upgrade loopx
loopx-kunluncode install
loopx-kunluncode --help

贡献者才需要 checkout-local 环境：

export LOOPX_SOURCE=/path/to/loopx
cd "$LOOPX_SOURCE"
uv venv .venv
uv pip install --python .venv/bin/python -e . 'mcp==1.28.1'
export LOOPX_KUNLUN="$LOOPX_SOURCE/.venv/bin/loopx-kunluncode"
"$LOOPX_KUNLUN" install --python "$LOOPX_SOURCE/.venv/bin/python"

"$LOOPX_KUNLUN" --help 应列出 connect / install / uninstall / add / run / status；内置 provisioner 不修改系统 Python。

连接项目

新项目：创建 goal 并安装 MCP

"$LOOPX_KUNLUN" connect \
  --project "$TARGET_PROJECT" \
  --goal-id "$LOOPX_GOAL_ID" \
  --agent-id "$KUNLUN_AGENT_ID" \
  --objective "持续完成该项目中经过验证的实现任务"

当项目没有 .loopx/registry.json 时，--objective 必填。命令会 bootstrap goal、注册 peer Agent、加入 kunluncode backend、写项目绑定，并安装用户级 loopx-kunluncode MCP entry。

已有 LoopX goal

"$LOOPX_KUNLUN" connect \
  --project "$TARGET_PROJECT" \
  --goal-id "$LOOPX_GOAL_ID" \
  --agent-id "$KUNLUN_AGENT_ID"

使用 registry 中真实存在的 goal id。适配器会保留已有的 cc、Codex 或其他 Agent，再追加 KunlunCode 身份；不存在的 goal 会失败关闭。

拆开项目绑定和 MCP 安装

"$LOOPX_KUNLUN" connect \
  --project "$TARGET_PROJECT" \
  --goal-id "$LOOPX_GOAL_ID" \
  --agent-id "$KUNLUN_AGENT_ID" \
  --skip-mcp

"$LOOPX_KUNLUN" install

Native goal-pro/goal 由 app-server 外层回写，本身不依赖 MCP；--skip-mcp 后仍可运行。MCP 用于 readback、交互使用和 --mode headless。

验证连接

"$LOOPX_KUNLUN" status \
  --project "$TARGET_PROJECT"

kunluncode --cwd "$TARGET_PROJECT" mcp test loopx-kunluncode
kunluncode config get mcp_servers

状态应显示正确 goal 与 Agent；若安装 MCP，MCP test 应列出四个 LoopX 工具。源码贡献者还应运行 examples/kunluncode-app-server-goal-pro-smoke.py --require，证明 2026-07-27、mode=strict、status=complete、verification_passed=true 和跨进程同 thread 恢复。

should_run=false 可能只是当前没有工作、处于 gate、等待 cadence 或已经终态，并不自动表示安装失败。

添加并运行任务

添加一个有界 todo

"$LOOPX_KUNLUN" add \
  --project "$TARGET_PROJECT" \
  "修复配置解析问题，运行相关测试，并记录通过结果"

add 会把 todo 绑定并 claim 给当前 KunlunCode Agent。任务文本应包含清晰完成条件，但不应包含密钥、原始日志或私有材料。

默认：可恢复的原生 Goal Pro

"$LOOPX_KUNLUN" run \
  --project "$TARGET_PROJECT" \
  --mode goal-pro \
  --permission-mode auto \
  --max-duration-secs 600 \
  --controller-timeout-secs 3600

控制器先由 LoopX 选择/claim todo，再创建或恢复 app-server thread，设置 mode=strict 的 Goal，启动首轮并等待原生 auto-continuation。只有 complete + verification_passed 才执行 delivery、todo、quota 三阶段回写。

其他显式模式

# 普通 native Goal（无严格 verifier gate）
loopx-kunluncode run --project "$TARGET_PROJECT" --mode goal

# 旧版一轮一进程 MCP worker
loopx-kunluncode run --project "$TARGET_PROJECT" \
  --mode headless --permission-mode auto

Legacy worker 仍要求模型在 next_agent_todo 与 no_follow_up=true 中二选一；native 模式的 writeback 则由外层事务控制器完成。

--max-duration-secs 是每 turn 软预算，--controller-timeout-secs 是完整 Goal 等待预算；可选 --token-budget。机器消费输出时加 --json；只预览时加 --dry-run。

权限模式怎么选

身份、状态与安全边界

• Native Goal 激活不授予 write、push、publish、destructive、credential、external sink 或 production 权限。
• claim/complete 会验证请求 Agent 与项目绑定一致；冒充其他 lane 会失败。
• Native run 期间 MCP claim/complete 与 shell 中直接发往当前绑定 goal 的 LoopX lifecycle CLI 写命令都会失败关闭，防止模型在 verifier 前绕行提交。
• 只有 complete + verification_passed 后才执行 refresh、todo complete、quota spend。
• Refresh 显式 suppress external sinks；journal 不保存原始 objective、output 或 trajectory。
• 原始 transcript、长日志、provider 响应、密钥和本机路径不得进入公共提交。

常用维护命令

升级发布包或源码环境搬家后刷新 MCP

"$LOOPX_KUNLUN" install

kunluncode --cwd "$TARGET_PROJECT" mcp test loopx-kunluncode

停止执行但保留状态

停止调用 run 即可。适配器没有常驻 scheduler；active native Goal 的 opaque identity 留在本地 journal，之后同一命令会恢复。

卸载 LoopX 管理的 MCP entry

"$LOOPX_KUNLUN" uninstall

卸载器只删除能确认由 LoopX 管理的 entry；native app-server mode 仍可运行。解除项目绑定时删除 kunluncode.json。仅在 journal phase=committed 后删除 kunluncode-runtime.json；active 阶段删除代表明确放弃恢复。以上操作都不会删除 goal、todo、历史、KunlunCode thread 或其他 Agent。

故障排查

重新同步 Python 环境

cd "$LOOPX_SOURCE"
uv pip install --python .venv/bin/python -e . 'mcp==1.28.1'

"$LOOPX_KUNLUN" install --python "$LOOPX_SOURCE/.venv/bin/python"

should_run=false

读取 effective_action、reason、interaction_contract 与 scheduler_hint。没有 todo、终态、quota、user gate 或 monitor cadence 都可能正确阻止执行。

完整验收清单

• uv 可用；LoopX 与 mcp==1.28.1 位于同一环境。
• connect 返回成功，goal id 与 Agent id 正确。
• .loopx/kunluncode.json 未被 Git 跟踪。
• 已有 goal 的其他 registered agents 被保留。
• 若安装 MCP，MCP test 显示四个工具。
• status 显示 registered kunlun、host kunluncode、runtime profile kunluncode。
• 真实 app-server smoke 证明 strict Goal、verifier PASS 与跨进程 resume。
• 低风险 todo 只在 native Goal Pro verifier PASS 后完成 delivery/todo/quota writeback。
• status 显示 native phase=committed、verification_passed=true。
• 人为中断后重跑不会重复已完成 writeback 阶段。
• 错误 Agent id 被拒绝。
• 终态、quota 或 user gate 时停止重复运行。
• 凭据、私有状态、原始日志和本机路径未进入提交。

命令速查

# 连接或初始化
loopx-kunluncode connect --project DIR --goal-id ID [--agent-id ID] \
  [--objective TEXT] [--python PYTHON] [--skip-mcp] [--replace] [--dry-run]

# 安装 / 卸载用户级 MCP entry
loopx-kunluncode install [--python PYTHON] [--replace] [--dry-run]
loopx-kunluncode uninstall [--dry-run]

# 添加 todo、运行原生 Goal、读取状态
loopx-kunluncode add --project DIR TEXT...
loopx-kunluncode run --project DIR \
  [--mode goal-pro|goal|headless] \
  [--permission-mode ask|auto|accept-edits|dont-ask|bypass|yolo] \
  [--max-duration-secs N] [--controller-timeout-secs N] \
  [--token-budget N] [--json] [--dry-run]
loopx-kunluncode status --project DIR