{"_id":"@alivewavelab/wildarrange","name":"@alivewavelab/wildarrange","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@alivewavelab/wildarrange","version":"0.1.0","private":false,"description":"Linear governance runtime for Codex, Cursor, and Kimi Code agent workflows","repository":{"type":"git","url":"git+https://github.com/alivewavelab/WildArrange.git"},"homepage":"https://github.com/alivewavelab/WildArrange#readme","bugs":{"url":"https://github.com/alivewavelab/WildArrange/issues"},"type":"module","bin":{"helix":"bin/helix.mjs","wildarrange":"bin/helix.mjs"},"engines":{"node":">=20"},"scripts":{"test":"node --test","helix":"node ./bin/helix.mjs"},"gitHead":"fead8456e283275e196de85b743cbc0c0f25fa7e","_id":"@alivewavelab/wildarrange@0.1.0","_nodeVersion":"26.3.0","_npmVersion":"11.16.0","dist":{"integrity":"sha512-SQWZr/AwigFaDHXocB29gLHRB9bZbaOlq46d73N20SIDf3uqNWFoC/agqxriwgXy9oK16SR9J4w6tpb95gj2tg==","shasum":"5f5ba65e3acbbc3fd4db55177cc97dbcd9f171ac","tarball":"https://registry.npmjs.org/@alivewavelab/wildarrange/-/wildarrange-0.1.0.tgz","fileCount":138,"unpackedSize":754445,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQCh1WDl9kaZ4LS5KvzOoTss3cbMFVsoo7mF817ZOFVQEAIgSywhJzvV8j2dkGooB+5JRyvlHCttMVsF9pqUjmeRFA0="}]},"_npmUser":{"name":"bryanliu1988","email":"liuby1988@gmail.com"},"directories":{},"maintainers":[{"name":"bryanliu1988","email":"liuby1988@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/wildarrange_0.1.0_1785395066265_0.1899367723155192"},"_hasShrinkwrap":false}},"time":{"created":"2026-07-30T07:04:26.083Z","0.1.0":"2026-07-30T07:04:26.431Z","modified":"2026-07-30T07:04:26.740Z"},"maintainers":[{"name":"bryanliu1988","email":"liuby1988@gmail.com"}],"description":"Linear governance runtime for Codex, Cursor, and Kimi Code agent workflows","homepage":"https://github.com/alivewavelab/WildArrange#readme","repository":{"type":"git","url":"git+https://github.com/alivewavelab/WildArrange.git"},"bugs":{"url":"https://github.com/alivewavelab/WildArrange/issues"},"readme":"# WildArrange\n\n简体中文 | [English](./README.en.md)\n\nWildArrange 是面向 Codex、Cursor 与 Kimi Code 的本地 Agent 治理运行时。第一版刻意保持精简：先跑通**可恢复、可验证的单线闭环**，再考虑多 Agent 并行。\n\n## 它能做什么\n\nWildArrange 把一次编码请求变成带门禁的工作流：\n\n```text\ninit -> plan -> execute -> verify -> scope -> review -> checkpoint -> resume\n```\n\n核心规则：**worker 可以声称完成，但只有 gate 才能判定完成。**\n\n核心运行时是宿主中立的。Codex / Cursor / Kimi adapter 负责注入与恢复增强，但仅凭 CLI 也能跑完整流程。\n\n## 安装\n\n从 npm 包使用：\n\n```bash\nnpx @alivewavelab/wildarrange@latest init\nnpx @alivewavelab/wildarrange@latest adapter install\n```\n\n长期使用的项目建议安装为 devDependency，避免 hook 每次走网络：\n\n```bash\nnpm i -D @alivewavelab/wildarrange\nnpx wildarrange adapter install --mode local\n```\n\n本地开发（本仓库）：\n\n```bash\nnode ./bin/helix.mjs init\nnode ./bin/helix.mjs adapter install --target all --mode local\n```\n\n## 最小工作流\n\n创建计划 `plan.json`：\n\n```json\n{\n  \"title\": \"Todo app smoke\",\n  \"objective\": \"Write one verifiable artifact\",\n  \"tasks\": [\n    {\n      \"id\": \"T001\",\n      \"subject\": \"Write smoke artifact\",\n      \"writable_paths\": [\".helix/artifacts/smoke.txt\"],\n      \"worker_command\": \"node -e \\\"const fs=require('fs'); fs.mkdirSync('.helix/artifacts',{recursive:true}); fs.writeFileSync('.helix/artifacts/smoke.txt','ok\\\\n')\\\"\",\n      \"verify_commands\": [\"node -e \\\"const fs=require('fs'); if(fs.readFileSync('.helix/artifacts/smoke.txt','utf8').trim()!=='ok') process.exit(1)\\\"\"]\n    }\n  ]\n}\n```\n\n运行：\n\n```bash\nnode ./bin/helix.mjs plan --from plan.json\nnode ./bin/helix.mjs run\nnode ./bin/helix.mjs status\nnode ./bin/helix.mjs summary\n```\n\n或直接跑内置样例：\n\n```bash\nnode ./bin/helix.mjs workflow --sample\n```\n\n## 重要 API 约定\n\n`runNextTask` 返回的是**运行时下一步动作**，不等于任务持久状态。\n\nverifier 失败时，任务会回到 `pending` 等待重试，但返回值可能是：\n\n```json\n{\n  \"status\": \"retry\",\n  \"task\": { \"status\": \"pending\" }\n}\n```\n\n这是有意设计：`result.status` 表示运行时建议的下一步；`task.status` 表示磁盘上的任务状态。\n\n## Adapter\n\n```bash\nnode ./bin/helix.mjs adapter install --target all --mode local\nnode ./bin/helix.mjs adapter uninstall --target all\nnode ./bin/helix.mjs adapter restore --backup <backupId>\n```\n\n安装、卸载、恢复都会在 `.helix/adapters/` 写入报告；覆盖或删除前会备份已有 adapter 文件。`restore` 用于把 `.helix/adapters/backups/<backupId>/` 里的文件恢复回原位置。\n\n- **Codex**：生命周期 hook 写入 `.codex/hooks.json`，并在 `.helix/adapters/codex/hooks.json` 保留审计副本。Codex 需要在可信项目中通过 `/hooks` review / trust 后才会执行这些 hard hook。\n- **Cursor**：项目规则写入 `.cursor/rules/wildarrange.mdc`。当前 Cursor 侧是 soft governance，不等同于 Codex PreToolUse 硬拦截。\n- **Kimi Code**：生成项目专属 plugin 到 `.helix/adapters/kimi/plugin/`，复用项目根 `AGENTS.md` 和 `.agents/skills/`。WildArrange 不会静默改写用户级 `~/.kimi-code/config.toml`；从项目根启动 Kimi Code，显式执行 `/plugins install .helix/adapters/kimi/plugin`，再执行 `/reload`。不要给路径加引号，Kimi Code 0.27 会把引号当成路径字符。plugin 是用户级安装，但 bridge 会在非 WildArrange 项目中静默退出。\n\n`adapter install` 还会生成一组快捷命令，省去手动开终端敲 `node ...`。三端从同一套命令集渲染（`helix-config` / `helix-doctor` / `helix-refresh` / `helix-status` / `helix-plan` / `helix-approve` / `helix-run`）：\n\n- **Cursor**：`.cursor/commands/<name>.md`（纯 Markdown 斜杠命令，聊天输入 `/helix-doctor` 触发）。\n- **Codex / Kimi Code**：共享 `.agents/skills/<name>/SKILL.md` 项目 Skill；Codex 可通过 `/skills` 或 `$helix-doctor` 触发，Kimi Code 按其项目 Skill 机制发现和调用。\n\n每个命令本质是一段提示词，指示 AI 去执行对应的 `helix.mjs` 子命令并汇报结果——是\"让 AI 代你敲 CLI\"的快捷方式，不是原生按钮。\n\nKimi Hook 在正常运行时可拦截越界 Write/Edit 和明显高危 Bash，但 Kimi 的 Hook 执行器在 Hook 崩溃或超时时会 fail-open（失败放行）。因此它不能替代 WildArrange 的 verifier、scope、review、successCriteria、acceptance proof 与 checkpoint 最终质量门。\n\n## 多 Agent 最小闭环\n\n命令型子 Agent 可以先在隔离目录内并发运行；也可以通过 adapter 命令模板交给 Codex/Cursor 类宿主启动：\n\n```bash\nnode ./bin/helix.mjs parallel run --max-agents 2 --task T001,T002 --agent Kui --command \"...\"\nnode ./bin/helix.mjs parallel run --task T001 --agent Kui --adapter codex\nnode ./bin/helix.mjs parallel list\nnode ./bin/helix.mjs parallel status --run <runId>\nnode ./bin/helix.mjs parallel cleanup --run <runId>\n```\n\n子 Agent 若要提交主线成果，需要在 `agent-result.json` 写入结构化文件：\n\n```json\n{\n  \"summary\": \"artifact ready\",\n  \"files\": [\n    { \"path\": \"src/example.txt\", \"content\": \"ok\\n\" }\n  ]\n}\n```\n\n合入时不会直接信任子 Agent。`parallel admit` 会先检查 `writable_paths`，再跑 verifier、scope guard、review gate、acceptance proof 和 checkpoint：\n\n```bash\nnode ./bin/helix.mjs parallel admit --run <runId> --task T001\n```\n\n成功的子 Agent 结果不会立即关闭，而是保留为 `awaiting_user_acceptance`。只有 `parallel admit` 跑完整 gate 并完成 checkpoint 后，才会标记为 `released`。\n\n## 防御性校验\n\n```bash\nnode ./bin/helix.mjs config baseline --reason reviewed\nnode ./bin/helix.mjs config verify\nnode ./bin/helix.mjs state backup --reason before-risky-agent\nnode ./bin/helix.mjs state verify\nnode ./bin/helix.mjs state list\nnode ./bin/helix.mjs state restore --backup <backupId>\nnode ./bin/helix.mjs doctor\n```\n\n`doctor` 是一键体检：校验 config 结构与挂载、对账已完成任务（checkpoint / acceptance proof / ledger 事件必须齐全）、验证 ledger hash 链，并与最近一次备份交叉比对以发现整链重写。`state restore` 恢复前会自动再做一次备份，恢复错了可以再退回。\n\n每次 worker 执行前，WildArrange 会在 Git 项目里自动记录一份工作区快照（`git stash create`），快照 hash 与恢复命令写入任务证据和 ledger，代码被改坏时可用 `git stash apply <hash>` 还原。\n\nWildArrange 会在 shell 执行前阻断明显破坏性命令，例如删除 `.git/.helix`、递归删除 `src/test/doc` 等项目核心目录、`git reset --hard`、`git clean -fd`、`sudo` 或 `curl | sh`。正常项目命令、verifier、review command 和子 Agent runner 不受影响。\n\n用户验收后可以显式关闭保留结果：\n\n```bash\nnode ./bin/helix.mjs parallel close --run <runId> --task T001 --reason user_accepted\n```\n\nGit 项目可以使用 worktree 隔离。子 Agent 在独立 worktree 写文件，WildArrange 自动提取 patch；合入时同样先过 `writable_paths` 和完整 gate：\n\n```bash\nnode ./bin/helix.mjs parallel run --task T001 --isolation git-worktree --command \"...\"\nnode ./bin/helix.mjs parallel admit --run <runId> --task T001\n```\n\n## ArchivistRouter\n\nArchivistRouter 是“档案员 + 任务路由”节点。它只读取清洗后的结论包，不摄入代码块、raw diff 或完整命令输出。\n\n手动运行：\n\n```bash\nnode ./bin/helix.mjs archivist packet --text \"做一个网页版 TODO 工具\" --stage plan\nnode ./bin/helix.mjs archivist run --text \"做一个网页版 TODO 工具\" --stage plan --force\n```\n\n当 `archivistRouter.enabled` 为 `true` 时，`SessionStart`、`UserPromptSubmit`、`PostCompact` hook 会自动触发 ArchivistRouter。没有 DeepSeek key 时会走 deterministic fallback，不阻断主流程。\n\n路由采用双层策略：确定性关键词路由永远保留证据；如果配置了 `CangJie` provider，`routeGovernance.semanticShadow` 会给出语义第二意见。低置信或冲突的 `execute` 请求会降级为 `plan` / `ask`，避免模糊需求直接开工。\n\nArchivistRouter 的关键词学习不会直接改路由。建议先进入 `.helix/routing/suggestions/`，审核后才写入 `.helix/routing/routes-overrides.json`：\n\n```bash\nnode ./bin/helix.mjs archivist suggestions list\nnode ./bin/helix.mjs archivist suggestions resolve --id <id> --decision accept --evidence \"...\" --rationale \"...\"\n```\n\n跨会话记忆会写入 `.helix/memory/digests/`。任务完成、并行 admission 完成、`SessionStart` 和 `PostCompact` 会生成结构化 digest，用于恢复进展、决策、成果物、实现结论和踩坑记录。\n\n## Skill 与提示词变体\n\nSkill matcher 是路由之外的轻量解释层，用来判断当前阶段应加载哪些 skill：\n\n```bash\nnode ./bin/helix.mjs skills match --text \"做一个网页版提醒事项 App\" --stage design --agent YingLong\n```\n\n注入点的 Skill 挂载默认按需生效（`skillMatcher.dynamicInjection`）：有请求文本时，只有与本次请求匹配的已配置 skill 才注入全文，其余降级为\"按需可加载\"引用；`alwaysMount`（默认 `wildarrange-injection-runtime`）始终注入，`maxSkills`（默认 4）限制单次挂载数量。没有请求文本的注入点（如 `pre_tool_use`）回落到静态清单。动态匹配只做减法，不会把清单之外的 skill 全文塞进上下文。\n\n### 人工决策通道与安全开关\n\n- **通用推送（不绑任何外部 IM）**：所有\"待人决策\"的事项——计划待确认、改动越界的 ChangeRequest、失败任务、子 Agent 待验收——由 hook 在 SessionStart / UserPromptSubmit / PostCompact / Stop 时注入宿主 AI 上下文，要求 AI 主动向开发者复述并给出选项。`attentionReport` 是这份待办的真相源，`status` / dashboard 也能拉取。\n- **计划确认门**：`planApproval.required=true` 时，`plan --from` 导入的计划进入 `awaiting_plan_approval`，`run` 拒绝执行直到开发者 `plan approve`（或对话里用 `/helix-approve`）。默认关闭。\n- **命令安全外置**：内置高危命令正则是不可关闭的底线；`commandSafety.extraPatterns` 允许在其之上追加项目专属危险命令拦截（`{ id, pattern, flags, reason }`），无需改代码。\n\n提示词变体不替代 Agent 原始提示词，只追加模型偏置。GPT 系列和 Codex/Cursor 主模型默认走 `host` / `gpt` 配置，外部模型可按 provider 选择：\n\n```bash\nnode ./bin/helix.mjs prompts variant --agent YingLong --model gpt-5.5\nnode ./bin/helix.mjs prompts show --agent YingLong --variant gemini\n```\n\n## Dashboard\n\n本地启动：\n\n```bash\nnode ./bin/helix.mjs serve --host 127.0.0.1 --port 8765\n```\n\n绑定非 loopback 地址时必须带 token：\n\n```bash\nnode ./bin/helix.mjs serve --host 0.0.0.0 --port 8765 --token \"$HELIX_DASHBOARD_TOKEN\"\n```\n\nAPI 请求需携带以下之一：\n\n```text\nAuthorization: Bearer <token>\n```\n\n或：\n\n```text\nx-helix-token: <token>\n```\n\n本地 dashboard 的 `GET /api/state` 可在 loopback 下免 token 查看；所有 `POST` 写操作即使绑定 `127.0.0.1` 也必须带 token，并会校验 Host / Origin，避免网页静默触发本机 worker 命令。\n\n## 运行时文件\n\n| 路径 | 作用 |\n|---|---|\n| `.helix/team/tasks.json` | 任务状态 |\n| `.helix/ledger.jsonl` | 带 hash 链的追加式事件账本，可用 `node ./bin/helix.mjs ledger verify` 检查篡改 |\n| `.helix/security/config-baseline.json` | config hash 基线，可用 `node ./bin/helix.mjs config verify` 检查质量门是否被改弱 |\n| `.helix/backups/` | `state backup` 生成的运行态关键文件备份 |\n| `.helix/checkpoints/` | 已完成任务的 checkpoint |\n| `.helix/reports/` | workflow / review / failure 报告 |\n| `.helix/reports/acceptance/` | checkpoint 前的验收证明链 |\n| `.helix/snapshots/context.md` | 跨会话恢复上下文 |\n| `.helix/adapters/` | adapter 配置、报告与备份 |\n| `.helix/agent-runs/` | 子 Agent 运行包、结果与 admission 记录 |\n| `.helix/memory/` | ArchivistRouter 结构化记忆 |\n| `.helix/memory/digests/` | 跨会话恢复 digest |\n| `.helix/routing/suggestions/` | 待审核的路由关键词建议 |\n\n## 配置\n\n`helix.config.json` 配置 Agent、模型 provider、动态类别、上下文预算与注入点。\n\n`contextBudgets` 区分 Prompt、Markdown 与 Skill：Prompt / Markdown 默认保持短预算，已激活 Skill 默认可加载到 80,000 字符；超过预算时注入结果会显式标记 `truncated: true`，不会静默裁断。\n\n`\"provider\": \"host\"` 的 Agent 交给宿主工具处理：Codex 侧由 Codex 选模型，Cursor 侧走 adapter 默认模型，**不需要** WildArrange 自备 OpenAI API key。\n\n外部 provider 使用 OpenAI 兼容 HTTP 配置，详见 `helix.config.example.json`。环境变量模板见 `.env.wildarrange.example`：\n\n```bash\n# 复制后填入真实值，勿提交密钥\nsource .env.wildarrange\n```\n\n`apiKeyEnv` / `baseUrlEnv` 是**环境变量名**，不是密钥本身。`defaultBaseUrl` 在对应 env 未设置时作为回退地址。\n\n确定性 gate 不依赖模型 API。当 `review.llm.required` 为 `false` 时，缺少外部 key 或 host provider 只会告警，不会阻断线性状态机。\n\nLSP / 类型检查、AST 结构检查、hashline anchor 与注释检查走 CLI review gate，而非编辑器专属 hook：\n\n```json\n{\n  \"qualityGates\": {\n    \"lspDiagnostics\": {\n      \"enabled\": true,\n      \"commands\": [\"npm run typecheck\"]\n    },\n    \"astStructure\": {\n      \"enabled\": true,\n      \"commands\": [\"ast-grep --pattern 'console.log($A)' --lang ts --json src || true\"]\n    },\n    \"hashlineAnchors\": {\n      \"enabled\": true,\n      \"anchors\": [\n        { \"file\": \"src/app.ts\", \"line\": 12, \"sha256\": \"<hashLine>\" }\n      ]\n    },\n    \"commentChecker\": {\n      \"enabled\": true,\n      \"blockOnFindings\": false\n    }\n  }\n}\n```\n\n## 商业边界\n\nWildArrange 是受 Agent 治理模式启发的原创运行时，**不得**分发受限第三方项目的源码、prompt 原文或近似改写。\n\n商业发布前请确认：\n\n- 未包含受限第三方源码或 prompt 文本\n- `packs/` 中为 WildArrange 自著 prompt 与 tool 合同\n- 外部工作流参考仅保留为文档或概念对照\n\n## 开发\n\n```bash\nnpm test\nnpm pack --dry-run --cache /private/tmp/helix-npm-cache\n```\n\n当前状态：线性治理闭环已实现并通过测试；checkpoint 前会生成验收证明链，显式 `successCriteria` 只有绑定具体 verifier 命令或人工证据后才会通过。Codex adapter 已能写入项目 `.codex/hooks.json`，通过 `/hooks` trust 后具备 hard hook 拦截；Cursor 仍是 soft 规则注入。跨会话 digest 与 ArchivistRouter 会进入 hook 注入块；ledger 具备 hash 链校验；多 Agent 已具备命令型并行、Codex/Cursor 命令模板 spawn、结构化文件 admission、Git worktree patch admission、验收前保留与 admission 后释放。\n\n## 更多文档\n\n| 文档 | 说明 |\n|---|---|\n| [README.en.md](./README.en.md) | 英文版说明 |\n| [CLAUDE.md](./CLAUDE.md) | Agent / 开发者治理规范 |\n| [doc/concept.md](./doc/concept.md) | 产品概念与外部参考边界 |\n| [doc/project-architecture.md](./doc/project-architecture.md) | 运行时架构与 gate 模型 |\n| [doc/development-plan.md](./doc/development-plan.md) | P0 / P1 / P2 路线 |\n","readmeFilename":"README.md","_rev":"1-d66fe390a3f5a1187222e8625de1b1af"}