LazyZCode 文档

English · 简体中文

ZCode 纪律层的完整指南：计划 → 执行 → 拿证据 → 不做完不停。

安装

一个包装好 LazyZCode 的两半：lazyzcode:zw 插件（技能/钩子/角色）和 lzy CLI（目标循环状态机）。

前置条件

• macOS / Windows / Linux —— LazyZCode 对三平台都做引擎布局探测（macOS 应用包、Linux deb /opt/ZCode、Windows 每用户 %LOCALAPPDATA%\Programs\ZCode）， 绝不盲猜。
• ZCode 桌面端，已安装并登录。LazyZCode 跑在 ZCode 里面，没有单独的登录。
• Node.js ≥ 22 —— 任意在维护的 LTS。nvm 或 Homebrew 装的都行：当引擎的钩子 环境里没有 node 时，插件自带的启动器会扫这两个位置（Windows 经 nvm-windows/Program Files 解析；见 钩子与生命周期）。
• git —— 证据绑定用 git rev-parse HEAD^{tree}，干活的项目必须是 git 仓库。

安装

npm i -g lazyzcode
lzy install

lzy install 做三件事：插件载荷落位引擎插件缓存、写入 LazyZCode 自己的注册表 条目、经引擎官方 plugins enable 启用插件。它永不改写你的 config.json ——启用只走引擎自己的 CLI（ADR-0001）。

验证装好了

lzy status   # 快速体检；退出码 0 = 无 fail 级检查
lzy doctor   # 深度本地诊断（零遥测）

新开一个 ZCode 会话，在提示词开头输入 zw——编排引导应当到达，模型首行应显示 **ZW** engaged — LIGHT tier（或 HEAVY）。

卸载

lzy uninstall

删除已部署缓存与注册表条目，优先走引擎官方 plugins uninstall 路径。

推荐环境

概览

LazyZCode 装四样东西：

1. 一个插件（lazyzcode:zw），技能文本承载完整编排协议——triage、tier 选择、计划、执行、证据规则。
2. 六个钩子，接在引擎生命周期上：SessionStart（重注入循环状态）、 UserPromptSubmit（触发词）、PreToolUse（命令层 H3R 门——休眠原型）、 PostToolUse（注释轻提示）、PostToolUseFailure（同工具失败绊线）、Stop （有界续跑）。
3. 三只只读代理：lazyzcode:explorer、lazyzcode:plan-reviewer、 lazyzcode:qa-executor。
4. 一个 CLI（lzy），把目标循环实现为可跨会话存续的状态机：注册 → 计划门 → 执行 → 证据 → 终验门。

心智模型：计划里的勾是主张，真实表面证据才是事实。LazyZCode 的职责是让代理 把主张兑换成事实——并在它试图提前停手时把它拉回来。

第一个目标循环

在项目目录新开一个 ZCode 会话，输入：

zw 实现一个带测试的 CSV 导出接口

接下来会发生什么：

1. UserPromptSubmit 钩子命中句首的 zw，注入编排引导。
2. 模型宣告 **ZW** engaged — <tier> tier，并对任务做 triage（见 zw 协议）。
3. 用 CLI 注册目标（lzy loop register …），把计划文件写进 .lazyzcode/plans/。
4. 计划过计划门采纳——HEAVY 计划必须先过 lazyzcode:plan-reviewer。
5. 模型逐步执行，每完成一步调 lzy step done <ID>。F 项必须带绑定当前 tree hash 的 --evidence。
6. lzy loop finish 跑终验门：全部步骤 done、全部证据新鲜。此时目标才算完成。

循环开着时模型想停手，Stop 钩子会拉回——每会话至多 2 次。中断后（包括被限流 判死）恢复，发一句 zw 继续 即可；.lazyzcode/ 里的循环状态原封不动。

循环完成后腾位，跑 lzy loop reset。

常见问题

LazyZCode 的状态放哪？ 项目内的 .lazyzcode/（循环状态、计划、归档证据）。有意与 ZCode 自己的 .zcode/ 划清边界。不想提交就加进 .gitignore。

会偷偷上报数据吗？ 不会。零遥测。lzy doctor 报告的一切都从你本地的文件与引擎日志算出来。

会写我的 config.json 吗？ 永不。启用走引擎官方 plugins enable；安装器只部署文件、写 LazyZCode 自己的 注册表。

我的 zw 为什么没触发？ 匹配是分层的：裸 zw 只在提示词句首触发。句中 zw 被忽略（这是特性—— 「检查一下 zw 的钩子」是提问不是发起）。任意位置用显式全名 lazyzcode:zw， 或 ulw/ultrawork（词边界）。

lzy loop finish 为什么拒了我的证据？ 证据绑定取证当时所在提交的 tree hash。取证后又改了代码，证据按构造即过期—— 先提交，再 lzy step done <ID> --evidence … 重新取证。

撞上 [1302] 速率限制，是 LazyZCode 坏了吗？ 不是——那是 GLM 套餐的账号级并发限流。lzy doctor 的 rate-limit 行给出实测 压力与建议会话预算。见限流纪律。

钩子全无反应。 多半是引擎启动时 PATH 里没有 node（从 Dock 直启 ZCode.app 的常见场景）。 自带的 run-hook 启动器会自动兜底——POSIX 走 nvm/Homebrew，Windows 走 nvm-windows/Program Files；lzy doctor 的 hook-node 行告诉你它解析到了什么。详见 docs/diagnostics/2026-09-07-hook-spawn-env.md。

能同时跑两个目标循环吗？ 每个项目目录一个循环。已完成的循环会占位，直到 lzy loop reset 清掉。

能只用 CLI 不装插件（或反过来）吗？ 可以。CLI 到哪都能用；插件需要引擎。两者齐用效果最好——钩子和技能文本驱动 纪律，CLI 落实纪律。

触发词

* 这个示例不会进入循环——它是提及。注入是条件的：发起则进入协议，仅提及 则忽略并直接回答问题（「Mention ≠ invocation」）。zwift、azw、句中 zw 永不触发。

zw 协议

注入的技能文本（plugin/skills/zw/SKILL.md）定义模型遵守的契约：

1. 开场精确输出 **ZW** engaged — <LIGHT|HEAVY> tier。
2. Triage 定级。 LIGHT 用于小而收敛、低风险的活（1–2 项计划、单 F 项）。 HEAVY 用于多文件特性、架构、任何有风险或含糊的任务——先侦察再逐步计划。 LIGHT → HEAVY 随时可升，且要落盘：注册带 --tier heavy 或采纳前 lzy loop tier heavy（HEAVY 评审门由机器按落盘 tier 执法）。永不降级。
3. 用 CLI 注册目标。
4. 用 N/F 清单写计划（见计划门）。
5. 逐步执行，落提交、调 lzy step done <ID> 带注记——F 项带证据。
6. 在真实表面取证（见证据纪律）。
7. 过 CLI 终验门收口（见目标循环命令）。

协议还带行为红线（不伪造证据、不无声弃坑）和下面的限流规则。

0.1.0 起协议文本还标注执法层级——L0 协议约定、L1 CLI 机器门、L2 可信宿主 事件、L3 外部效应——读的人永远知道一条规则是靠承诺维持还是靠机器执法；并在 tier 之外立了第二根轴：risk_class（LOW / MED / HIGH / RESTRICTED，只升不 降），HIGH+ 禁入无人值守车道、RESTRICTED 直接硬断。审批绑不可变哈希 （INV-05）：计划采用在 L1 绑 planHash；对话里的人点头是 L0，exact-hash 人权门 落地前不因模型跑一条 CLI 而升格。

0.1.1 起拉回是认领资格制：只有认领了目标的会话（发 invocational 触发如 「zw 继续」写 claimedAt）才会被 Stop 拉回；认领集为空=无人可拉，旁路会话 结构性免拉。会话可显式退出——发「zw standdown」写 standdown 旗标，Stop 对 该会话只读放行，直到参与触发清旗标或目标 reset。宿主工作区必须是 git 仓： lzy loop register 对非 git 宿主直接硬拒并给 git init 指路——证据绑定 git 树，非 git 宿主的 finish 不可达（ADR-0019）。

目标循环命令

lzy loop register <slug> --title "…" [--tier heavy]   # 进入 planning；tier 默认 light
lzy loop plan <文件> [--review "…"] [--force]
lzy loop start                          # 记录基线 tree hash + 实测并发纪律行
lzy loop subject add <路径>             # 声明兄弟仓根（仅 executing；校验 git 仓/无包含关系）
lzy loop subject remove <路径>          # 移除 subject（missing 死锁出口；证据过期语义照走）
lzy loop subject list                   # 列 subject 集（空=单树 host）
lzy loop tier heavy                     # tier 升级，只升不降（机器门=采纳时点）
lzy loop claim [<id>] [--release]        # 步级认领（匿名、48h 互斥）；无参列可认领集
lzy step done <ID> [--note "…"] [--evidence "…"] [--evidence-file <文件>]…
lzy loop status                         # 进度、下一步、证据新鲜度、tier/subjects/快照
lzy loop verify                         # 证据时效审计（退出码 1 = 过期/未绑定）；逐树头哈希/脏态行
lzy evidence red <Fid> --evidence "…"   # 红半绑自己的面（waive-red --reason=一行豁免的机器形态）
lzy dag dependents <id|surface>         # 「什么依赖 X」（中央账本，只读）
lzy dag stale                           # 失效预览：对照现行复合指纹（只展示不进门）
lzy attest comparator --file <json>     # 对照判决落 attestation（HEAVY finish 强制 MATCH）
lzy loop finish                         # 终验门：全部 done+证据新鲜+全树 clean（HEAVY 另需 MATCH 对照）；落终验 attestation 并自动归档
lzy loop export                         # 重导出证据包
lzy loop handoff --snapshot <文件>       # 登记干净交接；下个 Stop 放行一次
lzy loop cost                           # 积分成本报表（常设系数+促销 overlay，只读）
lzy loop list [--root <目录>]           # 只读扫同级仓的目标循环
lzy loop history                        # 目标谱系（证据包∪存根∪尾注，只读）
lzy loop abandon | lzy loop reset       # 放弃 / 清状态

• lzy loop plan 解析 N/F 清单并拒绝待定（TBD）项。评审判决用 --review "plan-reviewer: PASS …" 传入；REVISE 判决即使 --force 也不越过， HEAVY 目标（落盘 tier）无 PASS 评审被机器拒。采纳还要过人权门（0.1.1， ADR-0018）：首次采纳被拒并给出短码（planHash 前 8 位）——把「批准 <短码>」原句 转给用户，等用户消息到达（批准记录只能由 UserPromptSubmit 钩子在真实用户消息上 写入，模型自跑命令或手写文件都不算数）后重跑采纳即过；批准后改计划文件=批准作废， 重采纳出新高码。LIGHT/HEAVY 双档同门。采纳即快照计划到 .lazyzcode/loop/snapshots/<slug>.md 并绑 goal.planHash（评审记录同带—— 评审绑被评审物；修订后复采纳必须重跑评审）。条目行下一行的 deps: N1,N2 声明前置 依赖——引用必须存在，自指/成环/孤儿 deps: 行都会被响亮拒绝（正文要引用 语法？行尾加 <!--lzy:allow-->）。
• lzy loop start 冻结基线 tree hash；漂移对照它报告。
• F 项的 lzy step done 不带 --evidence 会被拒。带新证据重跑即重绑定 （标记 ↻ 重取证）。
• lzy loop verify 是终验门的只审计变体（证据过期/未绑定/无目标时退出码 1）。
• lzy loop claim 为同目标多工人提供匿名步级认领：48h 互斥、按计划 deps: 依赖边 做阻塞校验、lzy step done 自动释放、--release 提前释放、无参列可认领集 （lzy loop status 标注 [claimed]/[blocked: …]）。
• lzy loop handoff --snapshot <文件> 登记干净交接：下个 Stop 一次性消费标记并 放行，不消耗续跑预算（目标保持 executing，状态在盘）。快照须已存在且 2h 内 有改动，并含 7 个强制节（剩余步骤/下一步动作/目标与进度/脏树清单/tree hash/ 风险与坑/复归指令；缺节或空节拒收，模板见 zw 技能 Continuation 节）；lzy loop reset 清扫残留标记（abandon 留着不动；重开循环前先 reset）。 每次登记与消费会在 .lazyzcode/loop/metrics.json 累加匿名计数 （registered/consumed，无会话身份）；计数跨 reset 永续， 在 lzy status/lzy loop status 可见。
• lzy loop risk <level> 登记目标 risk_class（0.2.0，ADR-0020）：low|med|high| restricted 只升不降。HIGH/RESTRICTED 禁入无人值守车道（drive 入口机器门执法； triage 自评仍是协议文本）——执行中升到 HIGH+ 即 SUSPENDED_RISK 信号：收束交回人工。
• 多树并行（各 worktree 独立槽位各立目标）0.2.0 起为受支持形态：各树账本互盲 （各自 .lazyzcode/ 持自己的证据包与 attestation——用 lzy loop list --root 旁视兄弟仓），而未合并旁支上的 Goal: 尾注提交已计入 history/salvage/doctor 账本（git log --all）。
• lzy loop list 是只读诊断：扫一级同级目录（默认锚=当前目录的父目录，含自身； --root 可覆盖），打印各仓的目标 slug、状态、步骤进度、认领、新鲜度与存根。 单个仓状态文件读不出不炸全局——该行显示「版本不符」。
• lzy loop abandon 放弃但留档；lzy loop reset 清状态（含会话计数与孤儿 临时文件），下一个循环才能开。

计划门

计划是带两类条目的 markdown 清单：

- [N1] 在 src/api/export.ts 实现导出接口
- [N2] 实现 CSV 序列化与引号转义规则
deps: N1
- [F1] `curl localhost:3000/export` 返回 200 且可按 CSV 解析（qa-executor）

• N 项（实现项）描述工作。
• F 项（终验项）指名一个真实表面和将在其上取的证据。没有 F 项的计划 过不了门。
• subjects（可选，多树目标）：计划头 subjects: <路径> 行——每行一路径、 仅计划头（首个条目之前）、相对路径按宿主根解析。每根必须存在、是 git 仓、 与宿主无包含关系（只认兄弟仓根）。声明的 subject 进入证据指纹与 finish 闸门； 中途 add/remove 会使全体已录 F 证据过期。
• 依赖边（可选）：条目行下一行的裸小写 deps: 列出大小写敏感的 N/F 条目 id（自动去重）。未知引用、自指、成环、孤儿 deps: 行一律响亮拒绝。
• 计划必须决策完备：无 TBD、无「回头再定」。待定项在采纳时即被拒。 （若计划确实需要这个字面量，行级 <!--lzy:allow--> 标记可豁免。）
• HEAVY 目标（落盘 tier）还要经 --review 记录一条 plan-reviewer PASS—— 机器在采纳时点执法：任意非 PASS 串（含不带评审）一律拒，--force 不越过。 评审者核查决策完备性、隐藏风险、以及每个 F 项是否指名了可取证的表面。

已知未知

决策完备指「没有悬而未决的抉择」，不是「没有未验证的前提」。HEAVY 计划因此 以一节显性的已知未知收尾：列 1–3 条计划默默依赖的假设，每条带证伪 途径——什么信号证明它错、怎么查。写「无」可以，但须一行说明扫过哪里。

这节与计划门互补而非放松：它陈述的是未验证前提，不是推迟的决策——门照样 逐行扫描全节，段内出现真正的 TBD 与任何其他行一样被拒。评审者对照隐藏风险 审它：每条是否可证伪、「无」是否可信？

证据纪律

• 证据来自真实表面：某条 CLI 的 stdout、某个 HTTP 返回、一张截图——不是 模型自己的总结，也不只是「测试全绿」（测试运行只是众多表面之一）。
• 证据绑定复合指纹——{host}∪subjects 每根 git rev-parse HEAD^{tree} 头树哈希按 realpath 排序串接后的 sha256。先提交，再取证。 未提交的改动 不算数；任一 subject 树变化（或 subject 集本身增删）都使证据过期。 legacy 证据（0.0.8 前录取）按单树 host 比对，行为不变。
• 双证据（红绿两半）。默认每条 F 项断言要两半证据：红半=改动前状态 上断言失败的取证（动手改之前先取），绿半=改动后通过的取证。表面确实 构造不出反态的，在证据文本里写一行豁免说明——豁免要讲理由，不是静默跳过。 0.1.0 起红半可声明 harness（取证程序串，--harness "<命令>"）：哈希入 账本，红绿两半程序不同源会被标记——HEAVY 目标在 finish 直接拒（INV-08）。 HEAVY finish 还拒「锚定绿半无任何红半或豁免」的 F 项（INV-09）：缺红不得以 补绿收口——把红半补录上（事后补也行，账本会把它反向配对到现行锚定绿）， 或诚实豁免。
• 代码一变，旧证据按构造过期。终验门重查新鲜度，拒绝过期与未绑定证据。
• 取证产物（截图/响应转储）用 --evidence-file 随证据入账：lzy 复制进 .lazyzcode/evidence/ 并绑定 sha256（每 F 项 ≤4 个）；lzy loop finish 自动归档证据包到 .lazyzcode/evidence/<slug>.report.md——原子化：报告先写、 goal 后置 done，归档失败目标保持 executing 并给恢复指引（不再是「⚠ 失败但 done 已置」）。完整性闸门另要求 {host}∪subjects 每根 clean——脏/missing/ git 报错一律拒（无绕过 flag）。lzy loop export 随时重导出。
• lazyzcode:qa-executor 代理为此而生：派它去跑取证，并原样报告它实际观察到 的东西——命令与原始输出。它的天职是对抗证据造假。
• 证据对照（comparator）。存在性与新鲜度是机器门；证据是否真的证明了 断言所言，没有 CLI 读得懂语义——所以 HEAVY 目标 finish 前派 qa-executor 做对照：逐 F 项把断言对着已取证据判，不匹配就回去真重取证（或诚实修计划）。 证了一个差一点的定理，仍然不等于证了那一个。

续跑预算

ZCode 给每会话一个 3 次 stop-continuation 的共享池，后台任务通知也从这里 扣。LazyZCode 的 Stop 钩子每会话至多花 2 次，有意预留 1 次。计数按 sessionId 隔离（曾有一个全局计数的探针劫持了无关会话——这条约束现在是结构性的）。 钩子任何异常一律 fail-open：循环绝不困住不属于它的会话；预算花完后用户的 明确停止永远赢。

SessionStart 重注入循环状态，新会话接着上一个停下的地方干。

项目记忆

对一个没人画过地图的代码库做 HEAVY 规划，是在浪费计划门。lazyzcode:init-deep ——插件的第二个技能——构建分层项目记忆：一张根 AGENTS.md 地图，加上 够格子目录的分层地图（构建入口、直接文件数 > 40 的目录、根文件已提及的目录）。 ZCode 原生读取 AGENTS.md，地图免费搭进每一个未来会话——不需要任何钩子。

技能的契约是保守的：先出草稿，你点头才写盘；已有文件只给补丁建议、绝不覆盖； 不写密钥、不写本机路径。它只动 AGENTS.md 这一层——个人教训在 zw 收尾时归 宿主原生 memory。

lzy agents-md 列出够格目录与覆盖缺口；lzy doctor 的 agents-md 行巡逻 采纳情况（warn-only：没有根地图的仓库是 skip，不催）。HEAVY 规划在有地图时 先看地图。

无人值守

无人值守就是同一个目标循环挂上日程。引擎自带自动化以 zw 继续（无人值守：…） 唤起新会话；唤起节奏天然错峰——lzy doctor 的 schedule 行从你实测的限流 集中时段反推对侧 8 小时窗口，再对照已知平台高峰计价表（GLM/DeepSeek，写死的 UTC+8 静态表、人工维护）标注重叠并给出计价安全窗。计价表会过期——把该行当作 「实测限流 + 声明式计价」，不是保证。

护栏是结构性的，不是口头承诺：无人值守会话只继续已开的目标——绝不注册 新目标、绝不写或采纳计划，因为决策完备门需要人。没有可继续的目标就干净退出； 唤起本身受续跑预算、429 判死、串行子代理、≥1 小时间隔约束。

0.2.0 起唤起内还有执行通道：lzy loop drive 在一次唤起内拉起多个 headless 引擎段、逐段推进 executing 目标。段间查门——运行持分钟级租约（单运行时互斥、 心跳续期），每次运行配新开一份墙钟+积分预算，HIGH+ 风险目标在 spawn 之前就被 机器拒。每段的 lzy 写都带本运行 fence 令牌——被接管的运行写路径 fail-closed 停手，绝不污染循环状态。收束干净且可枚举：done、预算尽、段数尽、连续两段 零推进（stuck）——另有两因只存在于休眠 H3R 原型的车道（原型休眠时恒不出现）：高危步 停摆（h3r）、或在工具边界被拦下的高危命令（PreToolUse）——除 done 外的每次收束都由机器自写 7 字段交接快照并登记标记， 下一会话（或人工 zw 继续）从盘面接续。lzy doctor 的 drive 行报告本机通道 可用性：

lzy loop drive [--wall-ms N] [--max-segments N] [--mode m] [--workers N | --fast]

workers 波编排（0.2.4）。 lzy loop drive --workers N（糖 --fast≡N=2）每波在兄弟 worktree 上拉起 N 条工人链：步按认领门分派，工人各自在自己的 worktree 提交，波终 merge 回宿主并对全部已取证 F 项屏障重锚。合并冲突走干净收束、分支留人工。入口前提=env-auth 且 H3R 唤醒开关关闭；实测代价 turns≈2×、小任务可能反慢——启用前读实验报告 （docs/reviews/2026-fast-exp-report.md §1.3）。

宿主自动化仍是唯一定时唤起面——drive 是醒着之后跑的东西（也是你在无人值守 窗口里可以自己跑的）。

夜间战报不必等开电脑：把结果推到你自己的 IM 机器人 webhook（零服务端， lzy 不内置任何通知通道），配方见无人值守回执。

纪律角色

三只只读角色随插件 agents/ 目录分发，引擎自动发现。用 Agent 工具以角色作 subagent_type 派发：

三只全部只读：不改代码，其价值在于结论来自仓库本身，而非主代理的假设。

钩子与生命周期

六条命令都经 plugin/hooks/run-hook 启动：引擎用自己的环境拉起钩子，而 GUI 直启的 ZCode 可能 PATH 里没有 node。一份清单服务两个平台家族——POSIX shell 执行无扩展名的 run-hook 脚本，Windows 的 cmd.exe 经 PATHEXT 把同一 名字解析到 run-hook.cmd 孪生。启动器在 POSIX 兜底 nvm（取最高版本）与 Homebrew 位置（Windows 兜底 nvm-windows 与 Program Files），落空则记 /tmp/lzy-hook-launcher.log（Windows 为 %TEMP%\lzy-hook-launcher.log）并以 0 退出（fail-open）。lzy doctor 的 hook-node 检查报告解析结果。

限流纪律

GLM 套餐实行账号级并发限流（[1302] / 429）。没有可以配置绕开的固定阈值： 实测余量随套餐档位、时段、账号状态浮动——lzy doctor 从引擎日志（近 2 日）实测， 报告去重后的 429 回合、判死回合、最长连撞，以及（数据连贯时）经验并发带 （「N 会话干净 / M 会话撞线」）。仅警告，不翻退出码。

zw 技能承载的行为规则：

• 一次只跑一个目标循环；并行主会话宜少。
• 子代理并行度靠实测、不靠猜：lzy loop start 用同一份实测数据打印 「并发纪律」行——刚撞线或处于实测集中段→串行；连贯干净经验带→≤2； 窗内零 429 时→≤2（技能默认，仅限独立取证）。
• 风险压过配额：配额压力可以在 triage 时选 LIGHT，但绝不降低 HEAVY 的风险 门槛。
• 被 429 判死（引擎重试耗尽判回合死）后：干净收尾，等几分钟，zw 继续—— 循环状态还在。
• 传输死亡是另一族：请求根本没出本机（ENETDOWN 等，引擎常误标 「不可重试」）。恢复契约同款——干净收尾即可，.lazyzcode/ 分毫无损； lzy doctor 的 transport 行给它单独记账（不与限流混算）。
• 内容审核杀流是第三族：请求正常开流、模型生成中途被服务端内容审核掐断 （1301，输入或生成内容皆可能触发；引擎常误标 reason=unknown）。这类 死亡原地重试必复现——干净收尾后换新会话，或换一种问法让模型换条推理 路径；lzy doctor 的 content 行单独记账（不与限流混算）。
• 仓库 Wiki 生成共用你的池：桌面端的仓库 Wiki 功能以后台 lane 跑在同一 账号模型配额上——大 wiki 生成期间，别再叠加密集的无人值守唤起。

无人值守（宿主自动化）：挂载方式与只继续协议见无人值守；窗口来自 lzy doctor 的 schedule 行——实测集中段对照声明式计价高峰表， 不是拍脑袋。

CLI 参考

项目记忆：lazyzcode:init-deep 技能生成分层 AGENTS.md 地图（根 + 有资格子目录）， 草稿先行——未经你点头不落任何盘；lzy doctor 每次跑都巡逻覆盖。

lzy install                     部署插件 + 注册表 + 官方启用
lzy sync [--watch]              重新部署载荷（热重载；--watch 持续监听）
lzy status                      快速体检（退出码 0 = 无 fail 级检查）
lzy doctor                      深度本地诊断（零遥测）
lzy uninstall                   删缓存 + 注册表条目
lzy loop register <slug> --title <标题> [--tier heavy]   建目标（planning；HEAVY 无 PASS 评审机器拒）
lzy loop plan <文件> [--review <判决>] [--force]   采纳 N/F 清单（快照+绑 planHash）
lzy loop supersede <文件> [--review <判决>]   执行中改计划的 forward-only 出口（旧 attempt 置 superseded、开新代次，采纳门重走）
lzy loop start                  planning → executing；记录基线 tree hash + 打印实测并发纪律行
lzy loop subject add <路径>     声明兄弟仓根（仅 executing；校验+去重）
lzy loop subject remove <路径>  移除 subject（missing 死锁出口）
lzy loop subject list           列 subject 集
lzy loop tier heavy             tier 升级，只升不降（机器门=采纳时点）
lzy loop claim [<id>] [--release]  步级认领（多工人；阻塞校验；48h 互斥）
lzy loop risk <level>              risk_class 升级（low|med|high|restricted；只升不降；ADR-0020）
lzy loop lease acquire|heartbeat|release|reclaim  运行级认领（分钟级互斥；fence 令牌；
                                  reclaim=僵尸租约出口；ADR-0020）
lzy loop budget init|spend|remaining  运行预算（墙钟+积分双硬顶；ADR-0020）
lzy loop status                 进度、下一步、证据新鲜度、tier/subjects/快照
lzy loop verify                 证据时效审计（退出码 1 = 过期/未绑定/无目标）；逐树头哈希/脏态行
lzy step done <ID> [--note <注记>] [--evidence <证据>] [--evidence-file <文件>]…
lzy loop finish                 终验门：全部 done + 证据新鲜 + {host}∪subjects 全树 clean（HEAVY 另需 MATCH 对照）；落终验 attestation+原子归档
lzy loop export                 重导出证据包（<slug>.report.md）
lzy loop cost                   积分成本报表（常设系数+促销 overlay，只读）
lzy loop list [--root <目录>]   跨仓目标循环清单（只读）
lzy loop history                目标谱系（证据包∪存根∪尾注，只读）
lzy loop attempts               attempt 世系（attempt.json ∪ 中央账本派生，只读）
lzy loop abandon                放弃，留档
lzy loop reset                  清循环状态（含会话计数、孤儿临时文件）
lzy agents-md                   AGENTS.md 分层审计（退出码 1 = 缺口/超限）
lzy version                     打印版本

旗标：--note 上限 300 字符、--evidence 上限 4000、--evidence-file 可重复 （每 F 项 ≤4 个、单个 ≤20MB）；--force=true 与 --force 等价；--watch=<值> 会警告（它不吃值）。

诊断

lzy status 跑基础检查；lzy doctor 在其上加跑深度项。退出码：fail 级 发现翻成 1；warn 与 skip 永不翻。

状态与配置

LazyZCode 没有配置文件。一切皆推导：

环境变量：LZY_ZCODE_ENGINE 整体替换默认引擎候选列表（默认： /Applications/ZCode.app/Contents/Resources/glm/zcode.cjs）。这就是全部配置面。

隐私：零遥测；诊断本地计算、本地输出。

兼容性与限制

• 引擎探测与全安装链支持 macOS / Windows / Linux 三平台（ADR-0011）； 分发矩阵按 arm64 实证（Windows 11 / Ubuntu ARM 虚拟机活体），x64 覆盖以官方 下载矩阵文档声明。
• headless（--prompt）驱动引擎需要桌面端注入的模型凭据；机制已经探针 验证，活体 headless 验收顺延。
• 每个项目目录一个目标循环，且已完成的循环占位直到 lzy loop reset。 同一个目录开多个会话时：第二个目标会被 register 拒绝，而 done 的目标仍占着槽位—— 别去 reset 另一个会话正在跑的目标（那是它的执行状态，清掉只剩回收存根）；默认在 同一棵树里串行。要并行跑多个目标，就给每个目标单独开一个 git worktree，且 worktree 建在宿主树外面（建在树内的目录会被当成未跟踪文件，把宿主自己的 finish 拦掉）。 多个会话协作同一个目标时用步级认领（lzy loop claim）分工，但一次只让一个写者提交—— 任何人提交都会让别人的 F 项证据过期，任何人的未提交改动都会拦住所有人的 finish （先 lzy loop status 看认领与脏面再动手）。
• 触发匹配有意分层——想从句中进循环，用 lazyzcode:zw 或 ultrawork。

安全与信任面

LazyZCode 在你机器上跑什么、装在哪里、以及它刻意不防什么：

• 钩子执行本地代码。 六个生命周期事件会运行本插件的本地 Node 脚本 （UserPromptSubmit、SessionStart、Stop、PreToolUse、PostToolUse、PostToolUseFailure）。 其输出是对模型的注入上下文——模型读到的引导，不是沙箱边界。
• 安装落点是引擎官方插件缓存。 lzy install 把载荷落到那里，启用走引擎 官方 CLI；LazyZCode 绝不写你的 config.json（红线 1）。
• 双分发链，用户可自验。 npm：用 npm view lazyzcode dist.integrity 把 tarball 完整性哈希与发布时公示的 shasum 逐字核对。市场：manifest 钉 commit sha（pin=sha），你装载的载荷就是被钉的那棵树。
• 威胁模型边界（明示）： LazyZCode 防的是偷懒——假完成、无声弃坑； 不防恶意 agent：本地账本、批准记录、续跑计数对同权限进程全部可读写。 完整性声明的执法点是协议文本加审计环，不是防篡改硬件。

LazyZCode 以 MIT 许可发布。工作流受 lazycodex（MIT）启发； oh-my-openagent（OmO， SUL-1.0）仅贡献思想。文档结构参照 lazycodex 文档并注明出处。