命令手册

74 条命令，一条工作路径。

按物理命令和逻辑用途索引全部 CLI 入口。日常只需记住 workflow 主循环，其余能力由本地 gate 串联。

开发者心智模型

新项目先接入，既有项目先建基线；日常通过 workflow 命令启动，Graphify、policy、evidence 始终参与，文档/RAG 则按项目模式启用。

日常执行路径 local-only 默认

zl-init zl-codebase-scan zl-docs-sync zl-answer-audit zl-preflight zl-graph-build zl-debug zl-evidence-record zl-completion-check

通用规则

安装 bin 后推荐直接使用 zl-*。未安装全局 bin 时，可以在 Zhulong 仓库里使用 node bin/zl.mjs <subcommand>。默认流程必须是 local-only、interactive、no hidden heavy refresh：只执行当前 Skill，后续命令只能推荐；调查和诊断默认不修改。只有显式 --run、--index 或 zl-refresh-run 才允许重任务。

zl-docs-sync --target /path/to/repo
node bin/zl.mjs docs sync --target /path/to/repo

当前用户消息只授权它明确要求的工作，不提前接受结果；workflow alias 不会自动伪装成用户来源，只有直接响应当前用户消息的 runtime 才能附加 --source user-message。多 milestone 自动执行会先生成逐 MVP 的结构化合同，child workflow 必须携带 authorization ID、milestone、contract digest，并使用合同中的精确 objective；越界或撤销后停止。完成检查只读，显式 complete 才改变状态。

zl workflow authorize --target "$PWD" --source user-message   --request "自动执行 MVP4.0 到 MVP4.7，完成后停止"   --goal "MVP4 delivery" --contract-file ".planning/goals/MVP4_CONTRACTS.json"
zl workflow authorization-status --target "$PWD"
zl workflow permission-check --target "$PWD" --permission push
zl workflow revoke --target "$PWD" --reason "用户停止自动执行"
zl workflow complete --target "$PWD"

新项目从 0 接入

先接入 Zhulong，再安装 runtime pack，然后建立代码和 Graphify 基线，最后进入第一次 milestone。非文档密集型项目使用 rag none，无需准备 RAG。

cd /path/to/new-project

zl-init --target "$PWD" --template greenfield-app --name my_new_project --mode new --doc-policy reference --rag none
zl-runtime-install --runtime codex --dest ~/.codex/skills --force
zl-runtime-install --runtime claude-code --dest ~/.claude/skills --force
zl-runtime-install --runtime github-copilot --dest .github/prompts --force

zl-codebase-scan --target "$PWD"
zl-graph-build --target "$PWD" --run

zl-new-milestone --target "$PWD" "MVP1 walking skeleton"
zl-spec-phase --target "$PWD" "整理 MVP1 需求"
zl-plan-phase --target "$PWD" "MVP1 phase 1"
zl-execute-phase --target "$PWD" "实现第一条纵向链路"
zl-verify-work --target "$PWD" "验证 MVP1 phase 1"
zl-complete-milestone --target "$PWD" "MVP1 walking skeleton"

既有项目接入

既有项目不要移动原源码。Zhulong 只叠加 .planning/，先扫描已有代码；存在项目资料时再同步文档，然后从当前真实任务进入第一次 workflow。

cd /path/to/existing-project

zl-init --target "$PWD" --template brownfield-monorepo --name existing_project --mode existing --doc-policy reference --rag none
zl-codebase-scan --target "$PWD"
zl-codebase-status --target "$PWD"

zl-graph-build --target "$PWD" --run
zl-preflight --target "$PWD"

zl-debug --target "$PWD" "生产审批金额异常"

日常开发循环

日常优先使用 workflow 主循环命令。Graphify、policy、evidence 会作为 guard 和 next command 被串起来；只有启用 RAG 的项目才加入 GraphRAG gate。

zl-new-milestone --target "$PWD" "CR-017 退款上限修复"
zl-spec-phase --target "$PWD" "确认需求与验收条件"
zl-discuss-phase --target "$PWD" "确认实现策略"
zl-plan-phase --target "$PWD" "拆分实现和验证"
zl-execute-phase --target "$PWD" "实施改修"
zl-verify-work --target "$PWD" "跑测试并记录证据"
zl-complete-milestone --target "$PWD" "CR-017 收口"

文档更新循环

文档更新后默认只跑轻量同步，不自动重建 GraphRAG index。rag none 项目到此即可；本地 RAG 项目需要重索引时必须显式加 --index，并先确认 local-only 配置没有被改坏。

zl-docs-sync --target "$PWD"
zl-docs-query --target "$PWD" "退款 上限"
zl-answer-audit --target "$PWD"

# 只有明确需要重建本地 GraphRAG index 时才运行
zl-privacy-audit --target "$PWD" --strict
zl-docs-sync --target "$PWD" --index

质量验证循环

开发中用轻量 gate，收口时用质量闭环 gate。所有报告都留在本地仓库的 verification/reports/ 或目标项目的 .planning/ 下。

npm test
npm run verify:ci
npm run verify:release

# 只在本机已经准备好 Ollama / GraphRAG 时运行
npm run verify:local-rag

命令分类一览

物理名和逻辑名都可以点击跳到详情。heavy refresh 一列用于判断是否可能触发 GraphRAG index、Graphify build 或 refresh-run。

接入 / 初始化

物理名	逻辑名	分类	heavy refresh	主要产物
`zl`	统一 CLI 入口	接入 / 初始化	否；只做轻量检查、状态读取、报告写入或 workflow 编排。	`stdout help / command routing`
`zl-init`	初始化工作台	接入 / 初始化	否；只做轻量检查、状态读取、报告写入或 workflow 编排。	`AGENTS.md, project.manifest.yml, .planning/, .planning/INIT_PROFILE.md`
`zl-verify`	初始化完整性检查	接入 / 初始化	否；只做轻量检查、状态读取、报告写入或 workflow 编排。	`stdout ok/missing 检查结果`
`zl-map`	轻量结构地图	接入 / 初始化	否；只做轻量检查、状态读取、报告写入或 workflow 编排。	`.planning/codebase/STRUCTURE.md`

Codebase

物理名	逻辑名	分类	heavy refresh	主要产物
`zl-codebase`	代码基线扫描别名	Codebase	否；只做轻量检查、状态读取、报告写入或 workflow 编排。	`.planning/codebase/CODEBASE_STATUS.md, STRUCTURE.md, STACK.md, TESTING.md, ARCHITECTURE.md`
`zl-codebase-scan`	代码基线扫描	Codebase	否；只做轻量检查、状态读取、报告写入或 workflow 编排。	`.planning/codebase/CODEBASE_STATUS.md, STRUCTURE.md, STACK.md, TESTING.md, ARCHITECTURE.md`
`zl-codebase-status`	代码基线状态	Codebase	否；只做轻量检查、状态读取、报告写入或 workflow 编排。	`stdout codebase inventory 和 graph 状态`

文档 / RAG

物理名	逻辑名	分类	heavy refresh	主要产物
`zl-docs-scan`	文档来源扫描	文档 / RAG	否；只做轻量检查、状态读取、报告写入或 workflow 编排。	`.planning/knowledge/RAG_SOURCES.md, DOC_RAG_STATUS.md`
`zl-docs-status`	文档状态查看	文档 / RAG	否；只做轻量检查、状态读取、报告写入或 workflow 编排。	`stdout document context status`
`zl-docs-normalize`	文档归一化	文档 / RAG	否；只做轻量检查、状态读取、报告写入或 workflow 编排。	`.planning/knowledge/normalized/`
`zl-docs-extract`	文档文本抽取	文档 / RAG	否；只做轻量检查、状态读取、报告写入或 workflow 编排。	`.planning/knowledge/DOCUMENT_INDEX.json, DOCUMENT_EXTRACT_REPORT.md, extracted/`
`zl-docs-diff`	文档差分检查	文档 / RAG	否；只做轻量检查、状态读取、报告写入或 workflow 编排。	`.planning/knowledge/DOCUMENT_DIFF.md`
`zl-docs-citations`	文档引用检索	文档 / RAG	否；只做轻量检查、状态读取、报告写入或 workflow 编排。	`.planning/knowledge/CITATIONS.md`
`zl-docs-index`	GraphRAG 索引入口	文档 / RAG	默认否；只有 --run 才会执行 configured GraphRAG index。	`.planning/knowledge/RAG_INDEX_HANDOFF.md, 可选 RAG_INDEX_RESULT.md`
`zl-docs-query`	本地文档查询	文档 / RAG	否；只做轻量检查、状态读取、报告写入或 workflow 编排。	`.planning/knowledge/DOCS_QUERY_RESULT.md/json 或 RAG_QUERY_RESULT.md`
`zl-docs-sync`	文档轻量同步	文档 / RAG	默认否；只有 --index 才会显式执行 configured GraphRAG index。	`.planning/knowledge/DOCS_SYNC.md/json, 可选 RAG_INDEX_RESULT.md`
`zl-ambiguity-audit`	多语言暧昧表达审计	文档 / RAG	否；只做轻量检查、状态读取、报告写入或 workflow 编排。	`.planning/quality/AMBIGUITY_AUDIT.md/json`
`zl-structure-audit`	关键制品结构审计	文档 / RAG	否；只做轻量检查、状态读取、报告写入或 workflow 编排。	`.planning/quality/STRUCTURE_AUDIT.md/json`
`zl-answer-audit`	回答依据审计	文档 / RAG	否；只做轻量检查、状态读取、报告写入或 workflow 编排。	`.planning/quality/ANSWER_AUDIT.md/json`
`zl-rag-init-local`	本地 GraphRAG 初始化	文档 / RAG	否；只做轻量检查、状态读取、报告写入或 workflow 编排。	`graphrag-workspace/settings.yaml, graphrag-workspace/input/, .planning/knowledge/LOCAL_RAG_STATUS.md`
`zl-rag-golden-add`	RAG Golden 样例追加	文档 / RAG	否；只做轻量检查、状态读取、报告写入或 workflow 编排。	`.planning/knowledge/rag-golden/*.json`
`zl-rag-golden-run`	RAG Golden 评测	文档 / RAG	否；只做轻量检查、状态读取、报告写入或 workflow 编排。	`.planning/quality/RAG_GOLDEN_RUN.md/json`
`zl-rag-eval`	RAG 质量评估	文档 / RAG	否；只做轻量检查、状态读取、报告写入或 workflow 编排。	`.planning/quality/RAG_EVAL.md/json`
`zl-citation-audit`	引用证据审计	文档 / RAG	否；只做轻量检查、状态读取、报告写入或 workflow 编排。	`.planning/quality/CITATION_AUDIT.md/json`

Graphify / 代码地图

物理名	逻辑名	分类	heavy refresh	主要产物
`zl-graph-build`	Graphify 构建入口	Graphify / 代码地图	默认否；只有 --run 才会执行 configured Graphify / code map build。	`.planning/graphs/GRAPH_BUILD_HANDOFF.md, 可选 graph.json / GRAPH_REPORT.md / GRAPH_BUILD_RESULT.md`
`zl-graph-status`	代码地图状态	Graphify / 代码地图	否；只做轻量检查、状态读取、报告写入或 workflow 编排。	`stdout code map status`
`zl-graph-query`	代码地图查询	Graphify / 代码地图	否；只做轻量检查、状态读取、报告写入或 workflow 编排。	`stdout code map matches`
`zl-graph-diff`	代码图差分	Graphify / 代码地图	否；只做轻量检查、状态读取、报告写入或 workflow 编排。	`.planning/graphs/GRAPH_DIFF.md`
`zl-graph-impact`	代码影响面分析	Graphify / 代码地图	否；只做轻量检查、状态读取、报告写入或 workflow 编排。	`.planning/graphs/GRAPH_IMPACT.md/json`
`zl-graph-risk`	代码风险扫描	Graphify / 代码地图	否；只做轻量检查、状态读取、报告写入或 workflow 编排。	`.planning/graphs/GRAPH_RISK.md/json`
`zl-graph-freshness`	代码图新鲜度检查	Graphify / 代码地图	否；只做轻量检查、状态读取、报告写入或 workflow 编排。	`.planning/graphs/GRAPH_FRESHNESS.md/json`

Refresh / Mode

物理名	逻辑名	分类	heavy refresh	主要产物
`zl-preflight`	轻量前置检查	Refresh / Mode	否；只做轻量检查、状态读取、报告写入或 workflow 编排。	`.planning/refresh/PREFLIGHT.md/json`
`zl-refresh-plan`	刷新建议计划	Refresh / Mode	否；只做轻量检查、状态读取、报告写入或 workflow 编排。	`.planning/refresh/REFRESH_PLAN.md/json`
`zl-refresh-run`	显式刷新执行	Refresh / Mode	是；这是显式刷新命令，只在用户或 policy 明确要求时使用。	`.planning/refresh/REFRESH_RUN.md, REFRESH_STATE.json`
`zl-mode-status`	执行模式查看	Refresh / Mode	否；只做轻量检查、状态读取、报告写入或 workflow 编排。	`.planning/refresh/MODE.md`
`zl-mode-set`	执行模式切换	Refresh / Mode	否；只做轻量检查、状态读取、报告写入或 workflow 编排。	`.planning/config.json, .planning/refresh/MODE.md`

Evidence / Trace

物理名	逻辑名	分类	heavy refresh	主要产物
`zl-trace-build`	需求-代码-测试追踪矩阵	Evidence / Trace	否；只做轻量检查、状态读取、报告写入或 workflow 编排。	`.planning/trace/TRACE_MATRIX.md/json`
`zl-trace-query`	追踪矩阵查询	Evidence / Trace	否；只做轻量检查、状态读取、报告写入或 workflow 编排。	`stdout trace query result`
`zl-trace-audit`	追踪矩阵审计	Evidence / Trace	否；只做轻量检查、状态读取、报告写入或 workflow 编排。	`.planning/trace/TRACE_AUDIT.md/json`
`zl-evidence-record`	证据记录	Evidence / Trace	否；只做轻量检查、状态读取、报告写入或 workflow 编排。	`.planning/evidence/*.md, .planning/evidence/INDEX.md, 可选 writeback`
`zl-evidence-status`	证据状态	Evidence / Trace	否；只做轻量检查、状态读取、报告写入或 workflow 编排。	`.planning/evidence/INDEX.md 和 stdout summary`

Policy / Privacy

物理名	逻辑名	分类	heavy refresh	主要产物
`zl-policy-list`	策略列表	Policy / Privacy	否；只做轻量检查、状态读取、报告写入或 workflow 编排。	`.planning/policies/POLICY_LIST.md`
`zl-policy-check`	策略检查	Policy / Privacy	否；只做轻量检查、状态读取、报告写入或 workflow 编排。	`.planning/policies/POLICY_CHECK.md/json`
`zl-policy-explain`	策略解释	Policy / Privacy	否；只做轻量检查、状态读取、报告写入或 workflow 编排。	`.planning/policies/POLICY_EXPLAIN.md`
`zl-policy-lock`	策略快照锁定	Policy / Privacy	否；只做轻量检查、状态读取、报告写入或 workflow 编排。	`.planning/policies/POLICY_LOCK.md/json`
`zl-policy-verify`	策略锁验证	Policy / Privacy	否；只做轻量检查、状态读取、报告写入或 workflow 编排。	`.planning/policies/POLICY_VERIFY.md/json`
`zl-policy-diff`	策略漂移差分	Policy / Privacy	否；只做轻量检查、状态读取、报告写入或 workflow 编排。	`.planning/policies/POLICY_DIFF.md/json`
`zl-privacy-audit`	本地隐私审计	Policy / Privacy	否；只做轻量检查、状态读取、报告写入或 workflow 编排。	`.planning/knowledge/PRIVACY_AUDIT.md`
`zl-offline-lock`	离线锁定	Policy / Privacy	否；只做轻量检查、状态读取、报告写入或 workflow 编排。	`.planning/privacy/OFFLINE_LOCK.md/json`
`zl-outbound-audit`	外发风险审计	Policy / Privacy	否；只做轻量检查、状态读取、报告写入或 workflow 编排。	`.planning/privacy/OUTBOUND_AUDIT.md/json`
`zl-license-audit`	License 风险审计	Policy / Privacy	否；只做轻量检查、状态读取、报告写入或 workflow 编排。	`verification/reports/license-audit.md 或 .planning/license-audit.md`

Runtime / Skills

物理名	逻辑名	分类	heavy refresh	主要产物
`zl-runtime-install`	Runtime command pack 安装	Runtime / Skills	否；只做轻量检查、状态读取、报告写入或 workflow 编排。	`Codex/Claude Code skills 或 GitHub Copilot prompts`
`zl-runtime-status`	Runtime command pack 状态	Runtime / Skills	否；只做轻量检查、状态读取、报告写入或 workflow 编排。	`stdout runtime pack 渲染状态`
`zl-context-debug`	Debug 上下文包	Runtime / Skills	否；只做轻量检查、状态读取、报告写入或 workflow 编排。	`.planning/context/debug.md 和 handoff`
`zl-context-execute`	实施上下文包	Runtime / Skills	否；只做轻量检查、状态读取、报告写入或 workflow 编排。	`.planning/context/execute.md 和 handoff`

Workflow 主循环

物理名	逻辑名	分类	heavy refresh	主要产物
`zl-new-milestone`	开启里程碑循环	Workflow 主循环	否；只做轻量检查、状态读取、报告写入或 workflow 编排。	`.planning/context/, .planning/context/handoffs/, .planning/workflows/<id>/WORKFLOW_FACADE.md/json`
`zl-spec-phase`	需求整理阶段	Workflow 主循环	否；只做轻量检查、状态读取、报告写入或 workflow 编排。	`.planning/context/, .planning/context/handoffs/, .planning/workflows/<id>/WORKFLOW_FACADE.md/json`
`zl-discuss-phase`	讨论决策阶段	Workflow 主循环	否；只做轻量检查、状态读取、报告写入或 workflow 编排。	`.planning/context/, .planning/context/handoffs/, .planning/workflows/<id>/WORKFLOW_FACADE.md/json`
`zl-ui-phase`	UI 范围阶段	Workflow 主循环	否；只做轻量检查、状态读取、报告写入或 workflow 编排。	`.planning/context/, .planning/context/handoffs/, .planning/workflows/<id>/WORKFLOW_FACADE.md/json`
`zl-debug`	缺陷调查工作流	Workflow 主循环	否；只做轻量检查、状态读取、报告写入或 workflow 编排。	`.planning/context/, .planning/context/handoffs/, .planning/workflows/<id>/WORKFLOW_FACADE.md/json`
`zl-plan-phase`	计划阶段	Workflow 主循环	否；只做轻量检查、状态读取、报告写入或 workflow 编排。	`.planning/context/, .planning/context/handoffs/, .planning/workflows/<id>/WORKFLOW_FACADE.md/json`
`zl-execute-phase`	实施阶段	Workflow 主循环	否；只做轻量检查、状态读取、报告写入或 workflow 编排。	`.planning/context/, .planning/context/handoffs/, .planning/workflows/<id>/WORKFLOW_FACADE.md/json`
`zl-code-review`	代码审查工作流	Workflow 主循环	否；只做轻量检查、状态读取、报告写入或 workflow 编排。	`.planning/context/, .planning/context/handoffs/, .planning/workflows/<id>/WORKFLOW_FACADE.md/json`
`zl-verify-work`	工作验证阶段	Workflow 主循环	否；只做轻量检查、状态读取、报告写入或 workflow 编排。	`.planning/context/, .planning/context/handoffs/, .planning/workflows/<id>/WORKFLOW_FACADE.md/json`
`zl-complete-milestone`	完成里程碑	Workflow 主循环	否；只做轻量检查、状态读取、报告写入或 workflow 编排。	`.planning/context/, .planning/context/handoffs/, .planning/workflows/<id>/WORKFLOW_FACADE.md/json`

Workflow Guard

物理名	逻辑名	分类	heavy refresh	主要产物
`zl-workflow-run`	通用 workflow 启动	Workflow Guard	否；只做轻量检查、状态读取、报告写入或 workflow 编排。	`.planning/workflows/<id>/WORKFLOW_STATE.md/json, WORKFLOW_FACADE.md/json`
`zl-workflow-status`	workflow 状态查看	Workflow Guard	否；只做轻量检查、状态读取、报告写入或 workflow 编排。	`stdout gate 状态`
`zl-workflow-continue`	人工 gate 标记	Workflow Guard	否；只做轻量检查、状态读取、报告写入或 workflow 编排。	`.planning/workflows/<id>/WORKFLOW_STATE.md/json`
`zl-workflow-audit`	workflow 审计	Workflow Guard	否；只做轻量检查、状态读取、报告写入或 workflow 编排。	`.planning/workflows/<id>/WORKFLOW_AUDIT.md`
`zl-gate-check`	gate 检查	Workflow Guard	否；只做轻量检查、状态读取、报告写入或 workflow 编排。	`stdout gate result`
`zl-completion-check`	只读完成资格检查	Workflow Guard	否；只做轻量检查、状态读取、报告写入或 workflow 编排。	`stdout completion eligible/blocked（不修改状态）`

可视化 / Cockpit

物理名	逻辑名	分类	heavy refresh	主要产物
`zl-cockpit-build`	项目驾驶舱生成	可视化 / Cockpit	否；只读取已有本地 artifact，生成静态 HTML，不执行 GraphRAG index 或 Graphify build。	`.planning/cockpit/index.html, cockpit-data.json, COCKPIT_REPORT.md, assets/`

Help / Status

物理名	逻辑名	分类	heavy refresh	主要产物
`zl-help-skills`	场景命令推荐	Help / Status	否；只做轻量检查、状态读取、报告写入或 workflow 编排。	`.planning/help/HELP_SKILLS.md/json`
`zl-next`	下一步命令发现	Help / Status	否；只做轻量检查、状态读取、报告写入或 workflow 编排。	`.planning/help/NEXT.md`

全命令详情

下面每个公开命令都有独立锚点和同一套字段，供 README、runtime pack、QA 脚本和人工查阅共同引用。

`zl`

统一 CLI 入口

命令物理名: zl
命令逻辑名: 统一 CLI 入口
用途: 把 Zhulong 本地 intelligence layer 接入项目，或检查接入状态是否完整。
什么时候用: 项目接入、开发循环或完成前检查需要对应状态时。
基本语法: zl --help node bin/zl.mjs --help
参数说明: --help: 查看命令帮助。
默认行为: 读取本地项目状态并写入对应 .planning/ 报告，不默认执行重刷新。
是否触发 heavy refresh: 否；只做轻量检查、状态读取、报告写入或 workflow 编排。
输出文件 / 报告路径: stdout help / command routing
成功示例: zl --help node bin/zl.mjs --help
常见失败示例: 常见失败：目标项目未初始化或缺少 .planning/。先运行 zl-init --target "$PWD"。
关联命令: zl-verify zl-preflight zl-help-skills
适用场景: 项目接入、日常状态确认和质量闭环。

`zl-init`

初始化工作台

命令物理名: zl-init
命令逻辑名: 初始化工作台
用途: 把 Zhulong 本地 intelligence layer 接入项目，或检查接入状态是否完整。
什么时候用: 项目接入、开发循环或完成前检查需要对应状态时。
基本语法: zl-init --target "$PWD" --interactive zl-init --target "$PWD" --template brownfield-monorepo --name existing_project --mode existing --doc-policy reference --rag none zl-init --target "$PWD" --template brownfield-monorepo --mode existing --doc-policy strict --rag local --setup-rag skip zl-init --target "$PWD" --doc-policy strict --rag external --allow-external-rag
参数说明: --target <repo>: 指定目标项目目录。
--template <name>: 选择初始化模板。
--name <name>: 写入项目名。
--mode new|existing: 指定新项目或既存项目。
--doc-policy reference|strict: 选择文档是参考资料还是强约束依据。
--rag none|local|external: 选择不启用 RAG、本地 RAG 或外部 RAG。
--setup-rag ask|install|skip: 本地 RAG 依赖处理方式；默认 skip，只写 setup plan。
--allow-external-rag: 显式确认外部 RAG 可能导致文档内容离开本机。
--interactive: 强制进入 init wizard；真实终端只运行 zl-init --target <repo> 也会进入向导。
--no-interactive: 在真实终端中也跳过向导，使用显式参数或默认值。
--force: 覆盖已有模板文件。
默认行为: 真实终端默认进入 init wizard；CI/非 TTY 默认使用 reference + rag none + local_only。只叠加 .planning/ 和配置，不安装 RAG、不执行 GraphRAG index、不执行 Graphify build；strict 必须显式选择 local/external RAG。
是否触发 heavy refresh: 否；只做轻量检查、状态读取、报告写入或 workflow 编排。
输出文件 / 报告路径: AGENTS.md, project.manifest.yml, .planning/, .planning/INIT_PROFILE.md
成功示例: zl-init --target "$PWD" --interactive zl-init --target "$PWD" --template brownfield-monorepo --name existing_project --mode existing --doc-policy reference --rag none zl-init --target "$PWD" --template brownfield-monorepo --mode existing --doc-policy strict --rag local --setup-rag skip zl-init --target "$PWD" --doc-policy strict --rag external --allow-external-rag
常见失败示例: 常见失败：目标项目未初始化或缺少 .planning/。先运行 zl-init --target "$PWD"。
关联命令: zl-verify zl-preflight zl-help-skills
适用场景: 项目接入、日常状态确认和质量闭环。

`zl-verify`

初始化完整性检查

命令物理名: zl-verify
命令逻辑名: 初始化完整性检查
用途: 把 Zhulong 本地 intelligence layer 接入项目，或检查接入状态是否完整。
什么时候用: 项目接入、开发循环或完成前检查需要对应状态时。
基本语法: zl-verify --target "$PWD"
参数说明: --target <repo>: 指定目标项目目录。
默认行为: 读取本地项目状态并写入对应 .planning/ 报告，不默认执行重刷新。
是否触发 heavy refresh: 否；只做轻量检查、状态读取、报告写入或 workflow 编排。
输出文件 / 报告路径: stdout ok/missing 检查结果
成功示例: zl-verify --target "$PWD"
常见失败示例: 常见失败：目标项目未初始化或缺少 .planning/。先运行 zl-init --target "$PWD"。
关联命令: zl-verify zl-preflight zl-help-skills
适用场景: 项目接入、日常状态确认和质量闭环。

`zl-map`

轻量结构地图

命令物理名: zl-map
命令逻辑名: 轻量结构地图
用途: 把 Zhulong 本地 intelligence layer 接入项目，或检查接入状态是否完整。
什么时候用: 项目接入、开发循环或完成前检查需要对应状态时。
基本语法: zl-map --target "$PWD"
参数说明: --target <repo>: 指定目标项目目录。
默认行为: 读取本地项目状态并写入对应 .planning/ 报告，不默认执行重刷新。
是否触发 heavy refresh: 否；只做轻量检查、状态读取、报告写入或 workflow 编排。
输出文件 / 报告路径: .planning/codebase/STRUCTURE.md
成功示例: zl-map --target "$PWD"
常见失败示例: 常见失败：目标项目未初始化或缺少 .planning/。先运行 zl-init --target "$PWD"。
关联命令: zl-verify zl-preflight zl-help-skills
适用场景: 项目接入、日常状态确认和质量闭环。

`zl-codebase`

代码基线扫描别名

命令物理名: zl-codebase
命令逻辑名: 代码基线扫描别名
用途: 建立或读取代码基线，让后续 AI 修改先知道项目结构、技术栈、测试入口和源码数量。
什么时候用: 项目接入、开发循环或完成前检查需要对应状态时。
基本语法: zl-codebase --target "$PWD"
参数说明: --target <repo>: 指定目标项目目录。
默认行为: 读取本地项目状态并写入对应 .planning/ 报告，不默认执行重刷新。
是否触发 heavy refresh: 否；只做轻量检查、状态读取、报告写入或 workflow 编排。
输出文件 / 报告路径: .planning/codebase/CODEBASE_STATUS.md, STRUCTURE.md, STACK.md, TESTING.md, ARCHITECTURE.md
成功示例: zl-codebase --target "$PWD"
常见失败示例: 常见失败：目标项目未初始化或缺少 .planning/。先运行 zl-init --target "$PWD"。
关联命令: zl-verify zl-preflight zl-help-skills
适用场景: 项目接入、日常状态确认和质量闭环。

`zl-codebase-scan`

代码基线扫描

命令物理名: zl-codebase-scan
命令逻辑名: 代码基线扫描
用途: 建立或读取代码基线，让后续 AI 修改先知道项目结构、技术栈、测试入口和源码数量。
什么时候用: 项目接入、开发循环或完成前检查需要对应状态时。
基本语法: zl-codebase-scan --target "$PWD"
参数说明: --target <repo>: 指定目标项目目录。
默认行为: 读取本地项目状态并写入对应 .planning/ 报告，不默认执行重刷新。
是否触发 heavy refresh: 否；只做轻量检查、状态读取、报告写入或 workflow 编排。
输出文件 / 报告路径: .planning/codebase/CODEBASE_STATUS.md, STRUCTURE.md, STACK.md, TESTING.md, ARCHITECTURE.md
成功示例: zl-codebase-scan --target "$PWD"
常见失败示例: 常见失败：目标项目未初始化或缺少 .planning/。先运行 zl-init --target "$PWD"。
关联命令: zl-verify zl-preflight zl-help-skills
适用场景: 项目接入、日常状态确认和质量闭环。

`zl-codebase-status`

代码基线状态

命令物理名: zl-codebase-status
命令逻辑名: 代码基线状态
用途: 建立或读取代码基线，让后续 AI 修改先知道项目结构、技术栈、测试入口和源码数量。
什么时候用: 项目接入、开发循环或完成前检查需要对应状态时。
基本语法: zl-codebase-status --target "$PWD"
参数说明: --target <repo>: 指定目标项目目录。
默认行为: 读取本地项目状态并写入对应 .planning/ 报告，不默认执行重刷新。
是否触发 heavy refresh: 否；只做轻量检查、状态读取、报告写入或 workflow 编排。
输出文件 / 报告路径: stdout codebase inventory 和 graph 状态
成功示例: zl-codebase-status --target "$PWD"
常见失败示例: 常见失败：目标项目未初始化或缺少 .planning/。先运行 zl-init --target "$PWD"。
关联命令: zl-verify zl-preflight zl-help-skills
适用场景: 项目接入、日常状态确认和质量闭环。

`zl-docs-scan`

文档来源扫描

命令物理名: zl-docs-scan
命令逻辑名: 文档来源扫描
用途: 按需把需求、ADR、QA、会议记录、设计和运行文档转成本地可查、可引用、可审计的知识证据；rag none 项目无需建立 RAG 索引。
什么时候用: 需要查询或证明项目文档中的规格依据时。
基本语法: zl-docs-scan --target "$PWD"
参数说明: --target <repo>: 指定目标项目目录。
默认行为: 读取本地项目状态并写入对应 .planning/ 报告，不默认执行重刷新。
是否触发 heavy refresh: 否；只做轻量检查、状态读取、报告写入或 workflow 编排。
输出文件 / 报告路径: .planning/knowledge/RAG_SOURCES.md, DOC_RAG_STATUS.md
成功示例: zl-docs-scan --target "$PWD"
常见失败示例: 常见失败：缺文档抽取、关键制品缺失，或 --strict 下发现不合规。按审计报告中的 artifact 路径补齐。
关联命令: zl-docs-sync zl-ambiguity-audit zl-docs-query zl-answer-audit zl-structure-audit
适用场景: 文档更新循环、机械质量审计、规格依据确认和回答可信度检查。

`zl-docs-status`

文档状态查看

命令物理名: zl-docs-status
命令逻辑名: 文档状态查看
用途: 按需把需求、ADR、QA、会议记录、设计和运行文档转成本地可查、可引用、可审计的知识证据；rag none 项目无需建立 RAG 索引。
什么时候用: 需要查询或证明项目文档中的规格依据时。
基本语法: zl-docs-status --target "$PWD"
参数说明: --target <repo>: 指定目标项目目录。
默认行为: 读取本地项目状态并写入对应 .planning/ 报告，不默认执行重刷新。
是否触发 heavy refresh: 否；只做轻量检查、状态读取、报告写入或 workflow 编排。
输出文件 / 报告路径: stdout document context status
成功示例: zl-docs-status --target "$PWD"
常见失败示例: 常见失败：缺文档抽取、关键制品缺失，或 --strict 下发现不合规。按审计报告中的 artifact 路径补齐。
关联命令: zl-docs-sync zl-ambiguity-audit zl-docs-query zl-answer-audit zl-structure-audit
适用场景: 文档更新循环、机械质量审计、规格依据确认和回答可信度检查。

`zl-docs-normalize`

文档归一化

命令物理名: zl-docs-normalize
命令逻辑名: 文档归一化
用途: 按需把需求、ADR、QA、会议记录、设计和运行文档转成本地可查、可引用、可审计的知识证据；rag none 项目无需建立 RAG 索引。
什么时候用: 需要查询或证明项目文档中的规格依据时。
基本语法: zl-docs-normalize --target "$PWD"
参数说明: --target <repo>: 指定目标项目目录。
默认行为: 读取本地项目状态并写入对应 .planning/ 报告，不默认执行重刷新。
是否触发 heavy refresh: 否；只做轻量检查、状态读取、报告写入或 workflow 编排。
输出文件 / 报告路径: .planning/knowledge/normalized/
成功示例: zl-docs-normalize --target "$PWD"
常见失败示例: 常见失败：缺文档抽取、关键制品缺失，或 --strict 下发现不合规。按审计报告中的 artifact 路径补齐。
关联命令: zl-docs-sync zl-ambiguity-audit zl-docs-query zl-answer-audit zl-structure-audit
适用场景: 文档更新循环、机械质量审计、规格依据确认和回答可信度检查。

`zl-docs-extract`

文档文本抽取

命令物理名: zl-docs-extract
命令逻辑名: 文档文本抽取
用途: 按需把需求、ADR、QA、会议记录、设计和运行文档转成本地可查、可引用、可审计的知识证据；rag none 项目无需建立 RAG 索引。
什么时候用: 需要查询或证明项目文档中的规格依据时。
基本语法: zl-docs-extract --target "$PWD"
参数说明: --target <repo>: 指定目标项目目录。
默认行为: 读取本地项目状态并写入对应 .planning/ 报告，不默认执行重刷新。
是否触发 heavy refresh: 否；只做轻量检查、状态读取、报告写入或 workflow 编排。
输出文件 / 报告路径: .planning/knowledge/DOCUMENT_INDEX.json, DOCUMENT_EXTRACT_REPORT.md, extracted/
成功示例: zl-docs-extract --target "$PWD"
常见失败示例: 常见失败：缺文档抽取、关键制品缺失，或 --strict 下发现不合规。按审计报告中的 artifact 路径补齐。
关联命令: zl-docs-sync zl-ambiguity-audit zl-docs-query zl-answer-audit zl-structure-audit
适用场景: 文档更新循环、机械质量审计、规格依据确认和回答可信度检查。

`zl-docs-diff`

文档差分检查

命令物理名: zl-docs-diff
命令逻辑名: 文档差分检查
用途: 按需把需求、ADR、QA、会议记录、设计和运行文档转成本地可查、可引用、可审计的知识证据；rag none 项目无需建立 RAG 索引。
什么时候用: 需要查询或证明项目文档中的规格依据时。
基本语法: zl-docs-diff --target "$PWD"
参数说明: --target <repo>: 指定目标项目目录。
默认行为: 读取本地项目状态并写入对应 .planning/ 报告，不默认执行重刷新。
是否触发 heavy refresh: 否；只做轻量检查、状态读取、报告写入或 workflow 编排。
输出文件 / 报告路径: .planning/knowledge/DOCUMENT_DIFF.md
成功示例: zl-docs-diff --target "$PWD"
常见失败示例: 常见失败：缺文档抽取、关键制品缺失，或 --strict 下发现不合规。按审计报告中的 artifact 路径补齐。
关联命令: zl-docs-sync zl-ambiguity-audit zl-docs-query zl-answer-audit zl-structure-audit
适用场景: 文档更新循环、机械质量审计、规格依据确认和回答可信度检查。

`zl-docs-citations`

文档引用检索

命令物理名: zl-docs-citations
命令逻辑名: 文档引用检索
用途: 按需把需求、ADR、QA、会议记录、设计和运行文档转成本地可查、可引用、可审计的知识证据；rag none 项目无需建立 RAG 索引。
什么时候用: 需要查询或证明项目文档中的规格依据时。
基本语法: zl-docs-citations --target "$PWD" "退款上限"
参数说明: --target <repo>: 指定目标项目目录。
默认行为: 读取本地项目状态并写入对应 .planning/ 报告，不默认执行重刷新。
是否触发 heavy refresh: 否；只做轻量检查、状态读取、报告写入或 workflow 编排。
输出文件 / 报告路径: .planning/knowledge/CITATIONS.md
成功示例: zl-docs-citations --target "$PWD" "退款上限"
常见失败示例: 常见失败：缺文档抽取、关键制品缺失，或 --strict 下发现不合规。按审计报告中的 artifact 路径补齐。
关联命令: zl-docs-sync zl-ambiguity-audit zl-docs-query zl-answer-audit zl-structure-audit
适用场景: 文档更新循环、机械质量审计、规格依据确认和回答可信度检查。

`zl-docs-index`

GraphRAG 索引入口

命令物理名: zl-docs-index
命令逻辑名: GraphRAG 索引入口
用途: 按需把需求、ADR、QA、会议记录、设计和运行文档转成本地可查、可引用、可审计的知识证据；rag none 项目无需建立 RAG 索引。
什么时候用: 需要查询或证明项目文档中的规格依据时。
基本语法: zl-docs-index --target "$PWD" zl-docs-index --target "$PWD" --run
参数说明: --target <repo>: 指定目标项目目录。
--run: 显式执行配置的外部工具命令。
默认行为: 默认只写 handoff；带 --run 才执行 configured index_command。
是否触发 heavy refresh: 默认否；只有 --run 才会执行 configured GraphRAG index。
输出文件 / 报告路径: .planning/knowledge/RAG_INDEX_HANDOFF.md, 可选 RAG_INDEX_RESULT.md
成功示例: zl-docs-index --target "$PWD" zl-docs-index --target "$PWD" --run
常见失败示例: 常见失败：缺文档抽取、关键制品缺失，或 --strict 下发现不合规。按审计报告中的 artifact 路径补齐。
关联命令: zl-docs-sync zl-ambiguity-audit zl-docs-query zl-answer-audit zl-structure-audit
适用场景: 文档更新循环、机械质量审计、规格依据确认和回答可信度检查。

`zl-docs-query`

本地文档查询

命令物理名: zl-docs-query
命令逻辑名: 本地文档查询
用途: 按需把需求、ADR、QA、会议记录、设计和运行文档转成本地可查、可引用、可审计的知识证据；rag none 项目无需建立 RAG 索引。
什么时候用: 需要查询或证明项目文档中的规格依据时。
基本语法: zl-docs-query --target "$PWD" "退款上限" zl-docs-query --target "$PWD" --rag "退款规则的正式依据是什么？"
参数说明: --target <repo>: 指定目标项目目录。
--rag: 使用 configured RAG query command。
默认行为: 读取本地项目状态并写入对应 .planning/ 报告，不默认执行重刷新。
是否触发 heavy refresh: 否；只做轻量检查、状态读取、报告写入或 workflow 编排。
输出文件 / 报告路径: .planning/knowledge/DOCS_QUERY_RESULT.md/json 或 RAG_QUERY_RESULT.md
成功示例: zl-docs-query --target "$PWD" "退款上限" zl-docs-query --target "$PWD" --rag "退款规则的正式依据是什么？"
常见失败示例: 常见失败：缺文档抽取、关键制品缺失，或 --strict 下发现不合规。按审计报告中的 artifact 路径补齐。
关联命令: zl-docs-sync zl-ambiguity-audit zl-docs-query zl-answer-audit zl-structure-audit
适用场景: 文档更新循环、机械质量审计、规格依据确认和回答可信度检查。

`zl-docs-sync`

文档轻量同步

命令物理名: zl-docs-sync
命令逻辑名: 文档轻量同步
用途: 按需把需求、ADR、QA、会议记录、设计和运行文档转成本地可查、可引用、可审计的知识证据；rag none 项目无需建立 RAG 索引。
什么时候用: 文档第一次导入、需求/ADR/QA/运行资料更新，或文档 gate 需要重新确认时。
基本语法: zl-docs-sync --target "$PWD" zl-docs-sync --target "$PWD" --index
参数说明: --target <repo>: 指定目标项目目录。
--index: 显式允许同步后执行 GraphRAG index。
默认行为: 默认只跑 scan / diff / extract / citation audit，发现变更只写 STALE_NEEDS_REFRESH，不自动重建 index。
是否触发 heavy refresh: 默认否；只有 --index 才会显式执行 configured GraphRAG index。
输出文件 / 报告路径: .planning/knowledge/DOCS_SYNC.md/json, 可选 RAG_INDEX_RESULT.md
成功示例: zl-docs-sync --target "$PWD" zl-docs-sync --target "$PWD" --index
常见失败示例: 常见失败：缺文档抽取、关键制品缺失，或 --strict 下发现不合规。按审计报告中的 artifact 路径补齐。
关联命令: zl-docs-sync zl-ambiguity-audit zl-docs-query zl-answer-audit zl-structure-audit
适用场景: 文档更新循环、机械质量审计、规格依据确认和回答可信度检查。

`zl-ambiguity-audit`

多语言暧昧表达审计

命令物理名: zl-ambiguity-audit
命令逻辑名: 多语言暧昧表达审计
用途: 按需把需求、ADR、QA、会议记录、设计和运行文档转成本地可查、可引用、可审计的知识证据；rag none 项目无需建立 RAG 索引。
什么时候用: 规格、验收条件、QA 或会议结论更新后。
基本语法: zl-ambiguity-audit --target "$PWD" zl-ambiguity-audit --target "$PWD" --strict
参数说明: --target <repo>: 指定目标项目目录。
--strict: 把审计发现升级为阻断失败；默认只报告风险。
默认行为: 默认使用纯 Node 确定性规则生成报告，不联网、不调用 LLM、不阻断；--strict 才硬失败。
是否触发 heavy refresh: 否；只做轻量检查、状态读取、报告写入或 workflow 编排。
输出文件 / 报告路径: .planning/quality/AMBIGUITY_AUDIT.md/json
成功示例: zl-ambiguity-audit --target "$PWD" zl-ambiguity-audit --target "$PWD" --strict
常见失败示例: 常见失败：缺文档抽取、关键制品缺失，或 --strict 下发现不合规。按审计报告中的 artifact 路径补齐。
关联命令: zl-docs-sync zl-ambiguity-audit zl-docs-query zl-answer-audit zl-structure-audit
适用场景: 文档更新循环、机械质量审计、规格依据确认和回答可信度检查。

`zl-structure-audit`

关键制品结构审计

命令物理名: zl-structure-audit
命令逻辑名: 关键制品结构审计
用途: 按需把需求、ADR、QA、会议记录、设计和运行文档转成本地可查、可引用、可审计的知识证据；rag none 项目无需建立 RAG 索引。
什么时候用: 需要确认关键 planning 制品完整，或任务准备完成时。
基本语法: zl-structure-audit --target "$PWD" zl-structure-audit --target "$PWD" --strict
参数说明: --target <repo>: 指定目标项目目录。
--strict: 把审计发现升级为阻断失败；默认只报告风险。
默认行为: 默认使用纯 Node 确定性规则生成报告，不联网、不调用 LLM、不阻断；--strict 才硬失败。
是否触发 heavy refresh: 否；只做轻量检查、状态读取、报告写入或 workflow 编排。
输出文件 / 报告路径: .planning/quality/STRUCTURE_AUDIT.md/json
成功示例: zl-structure-audit --target "$PWD" zl-structure-audit --target "$PWD" --strict
常见失败示例: 常见失败：缺文档抽取、关键制品缺失，或 --strict 下发现不合规。按审计报告中的 artifact 路径补齐。
关联命令: zl-docs-sync zl-ambiguity-audit zl-docs-query zl-answer-audit zl-structure-audit
适用场景: 文档更新循环、机械质量审计、规格依据确认和回答可信度检查。

`zl-answer-audit`

回答依据审计

命令物理名: zl-answer-audit
命令逻辑名: 回答依据审计
用途: 按需把需求、ADR、QA、会议记录、设计和运行文档转成本地可查、可引用、可审计的知识证据；rag none 项目无需建立 RAG 索引。
什么时候用: 做完 docs/RAG query 后，或 AI 给出带规格结论的回答后。
基本语法: zl-answer-audit --target "$PWD" zl-answer-audit --target "$PWD" --from .planning/knowledge/DOCS_QUERY_RESULT.md
参数说明: --target <repo>: 指定目标项目目录。
--from <file>: 指定回答来源文件。
--answer <text>: 调试用，直接传入回答文本。
默认行为: 读取本地项目状态并写入对应 .planning/ 报告，不默认执行重刷新。
是否触发 heavy refresh: 否；只做轻量检查、状态读取、报告写入或 workflow 编排。
输出文件 / 报告路径: .planning/quality/ANSWER_AUDIT.md/json
成功示例: zl-answer-audit --target "$PWD" zl-answer-audit --target "$PWD" --from .planning/knowledge/DOCS_QUERY_RESULT.md
常见失败示例: 常见失败：目标项目未初始化或缺少 .planning/。先运行 zl-init --target "$PWD"。
关联命令: zl-docs-sync zl-ambiguity-audit zl-docs-query zl-answer-audit zl-structure-audit
适用场景: 文档更新循环、机械质量审计、规格依据确认和回答可信度检查。

`zl-rag-init-local`

本地 GraphRAG 初始化

命令物理名: zl-rag-init-local
命令逻辑名: 本地 GraphRAG 初始化
用途: 按需把需求、ADR、QA、会议记录、设计和运行文档转成本地可查、可引用、可审计的知识证据；rag none 项目无需建立 RAG 索引。
什么时候用: 需要查询或证明项目文档中的规格依据时。
基本语法: zl-rag-init-local --target "$PWD"
参数说明: --target <repo>: 指定目标项目目录。
默认行为: 读取本地项目状态并写入对应 .planning/ 报告，不默认执行重刷新。
是否触发 heavy refresh: 否；只做轻量检查、状态读取、报告写入或 workflow 编排。
输出文件 / 报告路径: graphrag-workspace/settings.yaml, graphrag-workspace/input/, .planning/knowledge/LOCAL_RAG_STATUS.md
成功示例: zl-rag-init-local --target "$PWD"
常见失败示例: 常见失败：目标项目未初始化或缺少 .planning/。先运行 zl-init --target "$PWD"。
关联命令: zl-docs-sync zl-ambiguity-audit zl-docs-query zl-answer-audit zl-structure-audit
适用场景: 文档更新循环、机械质量审计、规格依据确认和回答可信度检查。

`zl-rag-golden-add`

RAG Golden 样例追加

命令物理名: zl-rag-golden-add
命令逻辑名: RAG Golden 样例追加
用途: 按需把需求、ADR、QA、会议记录、设计和运行文档转成本地可查、可引用、可审计的知识证据；rag none 项目无需建立 RAG 索引。
什么时候用: 需要查询或证明项目文档中的规格依据时。
基本语法: zl-rag-golden-add --target "$PWD" --question "退款审批上限是多少？" --expect "30,000" --citation "docs/policy.md:12"
参数说明: --target <repo>: 指定目标项目目录。
默认行为: 读取本地项目状态并写入对应 .planning/ 报告，不默认执行重刷新。
是否触发 heavy refresh: 否；只做轻量检查、状态读取、报告写入或 workflow 编排。
输出文件 / 报告路径: .planning/knowledge/rag-golden/*.json
成功示例: zl-rag-golden-add --target "$PWD" --question "退款审批上限是多少？" --expect "30,000" --citation "docs/policy.md:12"
常见失败示例: 常见失败：目标项目未初始化或缺少 .planning/。先运行 zl-init --target "$PWD"。
关联命令: zl-docs-sync zl-ambiguity-audit zl-docs-query zl-answer-audit zl-structure-audit
适用场景: 文档更新循环、机械质量审计、规格依据确认和回答可信度检查。

`zl-rag-golden-run`

RAG Golden 评测

命令物理名: zl-rag-golden-run
命令逻辑名: RAG Golden 评测
用途: 按需把需求、ADR、QA、会议记录、设计和运行文档转成本地可查、可引用、可审计的知识证据；rag none 项目无需建立 RAG 索引。
什么时候用: 需要查询或证明项目文档中的规格依据时。
基本语法: zl-rag-golden-run --target "$PWD"
参数说明: --target <repo>: 指定目标项目目录。
默认行为: 读取本地项目状态并写入对应 .planning/ 报告，不默认执行重刷新。
是否触发 heavy refresh: 否；只做轻量检查、状态读取、报告写入或 workflow 编排。
输出文件 / 报告路径: .planning/quality/RAG_GOLDEN_RUN.md/json
成功示例: zl-rag-golden-run --target "$PWD"
常见失败示例: 常见失败：目标项目未初始化或缺少 .planning/。先运行 zl-init --target "$PWD"。
关联命令: zl-docs-sync zl-ambiguity-audit zl-docs-query zl-answer-audit zl-structure-audit
适用场景: 文档更新循环、机械质量审计、规格依据确认和回答可信度检查。

`zl-rag-eval`

RAG 质量评估

命令物理名: zl-rag-eval
命令逻辑名: RAG 质量评估
用途: 按需把需求、ADR、QA、会议记录、设计和运行文档转成本地可查、可引用、可审计的知识证据；rag none 项目无需建立 RAG 索引。
什么时候用: 需要查询或证明项目文档中的规格依据时。
基本语法: zl-rag-eval --target "$PWD"
参数说明: --target <repo>: 指定目标项目目录。
默认行为: 读取本地项目状态并写入对应 .planning/ 报告，不默认执行重刷新。
是否触发 heavy refresh: 否；只做轻量检查、状态读取、报告写入或 workflow 编排。
输出文件 / 报告路径: .planning/quality/RAG_EVAL.md/json
成功示例: zl-rag-eval --target "$PWD"
常见失败示例: 常见失败：目标项目未初始化或缺少 .planning/。先运行 zl-init --target "$PWD"。
关联命令: zl-docs-sync zl-ambiguity-audit zl-docs-query zl-answer-audit zl-structure-audit
适用场景: 文档更新循环、机械质量审计、规格依据确认和回答可信度检查。

`zl-citation-audit`

引用证据审计

命令物理名: zl-citation-audit
命令逻辑名: 引用证据审计
用途: 按需把需求、ADR、QA、会议记录、设计和运行文档转成本地可查、可引用、可审计的知识证据；rag none 项目无需建立 RAG 索引。
什么时候用: 需要查询或证明项目文档中的规格依据时。
基本语法: zl-citation-audit --target "$PWD"
参数说明: --target <repo>: 指定目标项目目录。
默认行为: 读取本地项目状态并写入对应 .planning/ 报告，不默认执行重刷新。
是否触发 heavy refresh: 否；只做轻量检查、状态读取、报告写入或 workflow 编排。
输出文件 / 报告路径: .planning/quality/CITATION_AUDIT.md/json
成功示例: zl-citation-audit --target "$PWD"
常见失败示例: 常见失败：目标项目未初始化或缺少 .planning/。先运行 zl-init --target "$PWD"。
关联命令: zl-docs-sync zl-ambiguity-audit zl-docs-query zl-answer-audit zl-structure-audit
适用场景: 项目接入、日常状态确认和质量闭环。

`zl-graph-build`

Graphify 构建入口

命令物理名: zl-graph-build
命令逻辑名: Graphify 构建入口
用途: 读取或更新 Graphify/code map，帮助判断改修影响面、风险模块和 stale 状态。
什么时候用: 改修前看影响面、改修后验证结构变化、或 graph gate 报 stale 时。
基本语法: zl-graph-build --target "$PWD" zl-graph-build --target "$PWD" --run
参数说明: --target <repo>: 指定目标项目目录。
--run: 显式执行配置的外部工具命令。
默认行为: 默认只写 handoff；带 --run 才执行 configured Graphify/code map command。
是否触发 heavy refresh: 默认否；只有 --run 才会执行 configured Graphify / code map build。
输出文件 / 报告路径: .planning/graphs/GRAPH_BUILD_HANDOFF.md, 可选 graph.json / GRAPH_REPORT.md / GRAPH_BUILD_RESULT.md
成功示例: zl-graph-build --target "$PWD" zl-graph-build --target "$PWD" --run
常见失败示例: 常见失败：.planning/graphs/graph.json 或 GRAPH_REPORT.md 缺失。先运行 zl-graph-build --target "$PWD" --run。
关联命令: zl-graph-build zl-graph-status zl-graph-query zl-graph-freshness
适用场景: 改修影响面、新规设计影响、代码审查前风险确认。

`zl-graph-status`

代码地图状态

命令物理名: zl-graph-status
命令逻辑名: 代码地图状态
用途: 读取或更新 Graphify/code map，帮助判断改修影响面、风险模块和 stale 状态。
什么时候用: 改修前看影响面、改修后验证结构变化、或 graph gate 报 stale 时。
基本语法: zl-graph-status --target "$PWD"
参数说明: --target <repo>: 指定目标项目目录。
默认行为: 读取本地项目状态并写入对应 .planning/ 报告，不默认执行重刷新。
是否触发 heavy refresh: 否；只做轻量检查、状态读取、报告写入或 workflow 编排。
输出文件 / 报告路径: stdout code map status
成功示例: zl-graph-status --target "$PWD"
常见失败示例: 常见失败：.planning/graphs/graph.json 或 GRAPH_REPORT.md 缺失。先运行 zl-graph-build --target "$PWD" --run。
关联命令: zl-graph-build zl-graph-status zl-graph-query zl-graph-freshness
适用场景: 改修影响面、新规设计影响、代码审查前风险确认。

`zl-graph-query`

代码地图查询

命令物理名: zl-graph-query
命令逻辑名: 代码地图查询
用途: 读取或更新 Graphify/code map，帮助判断改修影响面、风险模块和 stale 状态。
什么时候用: 改修前看影响面、改修后验证结构变化、或 graph gate 报 stale 时。
基本语法: zl-graph-query --target "$PWD" "PaymentService"
参数说明: --target <repo>: 指定目标项目目录。
默认行为: 读取本地项目状态并写入对应 .planning/ 报告，不默认执行重刷新。
是否触发 heavy refresh: 否；只做轻量检查、状态读取、报告写入或 workflow 编排。
输出文件 / 报告路径: stdout code map matches
成功示例: zl-graph-query --target "$PWD" "PaymentService"
常见失败示例: 常见失败：.planning/graphs/graph.json 或 GRAPH_REPORT.md 缺失。先运行 zl-graph-build --target "$PWD" --run。
关联命令: zl-graph-build zl-graph-status zl-graph-query zl-graph-freshness
适用场景: 改修影响面、新规设计影响、代码审查前风险确认。

`zl-graph-diff`

代码图差分

命令物理名: zl-graph-diff
命令逻辑名: 代码图差分
用途: 读取或更新 Graphify/code map，帮助判断改修影响面、风险模块和 stale 状态。
什么时候用: 改修前看影响面、改修后验证结构变化、或 graph gate 报 stale 时。
基本语法: zl-graph-diff --target "$PWD" --save-baseline zl-graph-diff --target "$PWD"
参数说明: --target <repo>: 指定目标项目目录。
默认行为: 读取本地项目状态并写入对应 .planning/ 报告，不默认执行重刷新。
是否触发 heavy refresh: 否；只做轻量检查、状态读取、报告写入或 workflow 编排。
输出文件 / 报告路径: .planning/graphs/GRAPH_DIFF.md
成功示例: zl-graph-diff --target "$PWD" --save-baseline zl-graph-diff --target "$PWD"
常见失败示例: 常见失败：.planning/graphs/graph.json 或 GRAPH_REPORT.md 缺失。先运行 zl-graph-build --target "$PWD" --run。
关联命令: zl-graph-build zl-graph-status zl-graph-query zl-graph-freshness
适用场景: 改修影响面、新规设计影响、代码审查前风险确认。

`zl-graph-impact`

代码影响面分析

命令物理名: zl-graph-impact
命令逻辑名: 代码影响面分析
用途: 读取或更新 Graphify/code map，帮助判断改修影响面、风险模块和 stale 状态。
什么时候用: 改修前看影响面、改修后验证结构变化、或 graph gate 报 stale 时。
基本语法: zl-graph-impact --target "$PWD" --files "src/approval.js"
参数说明: --target <repo>: 指定目标项目目录。
--files <paths>: 逗号分隔的变更文件。
默认行为: 读取本地项目状态并写入对应 .planning/ 报告，不默认执行重刷新。
是否触发 heavy refresh: 否；只做轻量检查、状态读取、报告写入或 workflow 编排。
输出文件 / 报告路径: .planning/graphs/GRAPH_IMPACT.md/json
成功示例: zl-graph-impact --target "$PWD" --files "src/approval.js"
常见失败示例: 常见失败：.planning/graphs/graph.json 或 GRAPH_REPORT.md 缺失。先运行 zl-graph-build --target "$PWD" --run。
关联命令: zl-graph-build zl-graph-status zl-graph-query zl-graph-freshness
适用场景: 改修影响面、新规设计影响、代码审查前风险确认。

`zl-graph-risk`

代码风险扫描

命令物理名: zl-graph-risk
命令逻辑名: 代码风险扫描
用途: 读取或更新 Graphify/code map，帮助判断改修影响面、风险模块和 stale 状态。
什么时候用: 改修前看影响面、改修后验证结构变化、或 graph gate 报 stale 时。
基本语法: zl-graph-risk --target "$PWD"
参数说明: --target <repo>: 指定目标项目目录。
默认行为: 读取本地项目状态并写入对应 .planning/ 报告，不默认执行重刷新。
是否触发 heavy refresh: 否；只做轻量检查、状态读取、报告写入或 workflow 编排。
输出文件 / 报告路径: .planning/graphs/GRAPH_RISK.md/json
成功示例: zl-graph-risk --target "$PWD"
常见失败示例: 常见失败：.planning/graphs/graph.json 或 GRAPH_REPORT.md 缺失。先运行 zl-graph-build --target "$PWD" --run。
关联命令: zl-graph-build zl-graph-status zl-graph-query zl-graph-freshness
适用场景: 改修影响面、新规设计影响、代码审查前风险确认。

`zl-graph-freshness`

代码图新鲜度检查

命令物理名: zl-graph-freshness
命令逻辑名: 代码图新鲜度检查
用途: 读取或更新 Graphify/code map，帮助判断改修影响面、风险模块和 stale 状态。
什么时候用: 改修前看影响面、改修后验证结构变化、或 graph gate 报 stale 时。
基本语法: zl-graph-freshness --target "$PWD" --strict
参数说明: --target <repo>: 指定目标项目目录。
--strict: 以严格 profile 语义处理失败。
默认行为: 读取本地项目状态并写入对应 .planning/ 报告，不默认执行重刷新。
是否触发 heavy refresh: 否；只做轻量检查、状态读取、报告写入或 workflow 编排。
输出文件 / 报告路径: .planning/graphs/GRAPH_FRESHNESS.md/json
成功示例: zl-graph-freshness --target "$PWD" --strict
常见失败示例: 常见失败：.planning/graphs/graph.json 或 GRAPH_REPORT.md 缺失。先运行 zl-graph-build --target "$PWD" --run。
关联命令: zl-graph-build zl-graph-status zl-graph-query zl-graph-freshness
适用场景: 改修影响面、新规设计影响、代码审查前风险确认。

`zl-preflight`

轻量前置检查

命令物理名: zl-preflight
命令逻辑名: 轻量前置检查
用途: 控制刷新预算和 profile，避免每个任务都重跑 GraphRAG 或 Graphify。
什么时候用: 进入 debug、plan、execute 前，确认 RAG/Graphify 是否 stale。
基本语法: zl-preflight --target "$PWD"
参数说明: --target <repo>: 指定目标项目目录。
--strict: 以严格 profile 语义处理失败。
默认行为: 读取本地项目状态并写入对应 .planning/ 报告，不默认执行重刷新。
是否触发 heavy refresh: 否；只做轻量检查、状态读取、报告写入或 workflow 编排。
输出文件 / 报告路径: .planning/refresh/PREFLIGHT.md/json
成功示例: zl-preflight --target "$PWD"
常见失败示例: 常见失败：目标项目未初始化或缺少 .planning/。先运行 zl-init --target "$PWD"。
关联命令: zl-verify zl-preflight zl-help-skills
适用场景: 项目接入、日常状态确认和质量闭环。

`zl-refresh-plan`

刷新建议计划

命令物理名: zl-refresh-plan
命令逻辑名: 刷新建议计划
用途: 控制刷新预算和 profile，避免每个任务都重跑 GraphRAG 或 Graphify。
什么时候用: 项目接入、开发循环或完成前检查需要对应状态时。
基本语法: zl-refresh-plan --target "$PWD"
参数说明: --target <repo>: 指定目标项目目录。
默认行为: 读取本地项目状态并写入对应 .planning/ 报告，不默认执行重刷新。
是否触发 heavy refresh: 否；只做轻量检查、状态读取、报告写入或 workflow 编排。
输出文件 / 报告路径: .planning/refresh/REFRESH_PLAN.md/json
成功示例: zl-refresh-plan --target "$PWD"
常见失败示例: 常见失败：目标项目未初始化或缺少 .planning/。先运行 zl-init --target "$PWD"。
关联命令: zl-verify zl-preflight zl-help-skills
适用场景: 项目接入、日常状态确认和质量闭环。

`zl-refresh-run`

显式刷新执行

命令物理名: zl-refresh-run
命令逻辑名: 显式刷新执行
用途: 控制刷新预算和 profile，避免每个任务都重跑 GraphRAG 或 Graphify。
什么时候用: 只有 refresh plan 或 strict policy 明确要求刷新时。
基本语法: zl-refresh-run --target "$PWD" --graph zl-refresh-run --target "$PWD" --rag
参数说明: --target <repo>: 指定目标项目目录。
--rag: 刷新 RAG。
--graph: 刷新 Graphify/code map。
--all: 两者都刷新。
--force: 忽略普通跳过建议。
默认行为: 显式刷新命令，会根据参数执行 RAG、Graphify 或两者，并更新 REFRESH_STATE。
是否触发 heavy refresh: 是；这是显式刷新命令，只在用户或 policy 明确要求时使用。
输出文件 / 报告路径: .planning/refresh/REFRESH_RUN.md, REFRESH_STATE.json
成功示例: zl-refresh-run --target "$PWD" --graph zl-refresh-run --target "$PWD" --rag
常见失败示例: 常见失败：目标项目未初始化或缺少 .planning/。先运行 zl-init --target "$PWD"。
关联命令: zl-verify zl-preflight zl-help-skills
适用场景: 项目接入、日常状态确认和质量闭环。

`zl-mode-status`

执行模式查看

命令物理名: zl-mode-status
命令逻辑名: 执行模式查看
用途: 控制刷新预算和 profile，避免每个任务都重跑 GraphRAG 或 Graphify。
什么时候用: 项目接入、开发循环或完成前检查需要对应状态时。
基本语法: zl-mode-status --target "$PWD"
参数说明: --target <repo>: 指定目标项目目录。
默认行为: 读取本地项目状态并写入对应 .planning/ 报告，不默认执行重刷新。
是否触发 heavy refresh: 否；只做轻量检查、状态读取、报告写入或 workflow 编排。
输出文件 / 报告路径: .planning/refresh/MODE.md
成功示例: zl-mode-status --target "$PWD"
常见失败示例: 常见失败：目标项目未初始化或缺少 .planning/。先运行 zl-init --target "$PWD"。
关联命令: zl-verify zl-preflight zl-help-skills
适用场景: 项目接入、日常状态确认和质量闭环。

`zl-mode-set`

执行模式切换

命令物理名: zl-mode-set
命令逻辑名: 执行模式切换
用途: 控制刷新预算和 profile，避免每个任务都重跑 GraphRAG 或 Graphify。
什么时候用: 项目接入、开发循环或完成前检查需要对应状态时。
基本语法: zl-mode-set --target "$PWD" docs-reference zl-mode-set --target "$PWD" docs-strict zl-mode-set --target "$PWD" graph-lite
参数说明: --target <repo>: 指定目标项目目录。
docs-reference|docs-strict: 推荐用户语义。
graph-lite|default-local-rag|full-strict: 兼容旧内部 profile。
默认行为: 读取本地项目状态并写入对应 .planning/ 报告，不默认执行重刷新。
是否触发 heavy refresh: 否；只做轻量检查、状态读取、报告写入或 workflow 编排。
输出文件 / 报告路径: .planning/config.json, .planning/refresh/MODE.md
成功示例: zl-mode-set --target "$PWD" docs-reference zl-mode-set --target "$PWD" docs-strict zl-mode-set --target "$PWD" graph-lite
常见失败示例: 常见失败：目标项目未初始化或缺少 .planning/。先运行 zl-init --target "$PWD"。
关联命令: zl-verify zl-preflight zl-help-skills
适用场景: 项目接入、日常状态确认和质量闭环。

`zl-trace-build`

需求-代码-测试追踪矩阵

命令物理名: zl-trace-build
命令逻辑名: 需求-代码-测试追踪矩阵
用途: 把验证结果、需求或决策依据、代码影响和测试覆盖写成可追踪证据。
什么时候用: 项目接入、开发循环或完成前检查需要对应状态时。
基本语法: zl-trace-build --target "$PWD"
参数说明: --target <repo>: 指定目标项目目录。
默认行为: 读取本地项目状态并写入对应 .planning/ 报告，不默认执行重刷新。
是否触发 heavy refresh: 否；只做轻量检查、状态读取、报告写入或 workflow 编排。
输出文件 / 报告路径: .planning/trace/TRACE_MATRIX.md/json
成功示例: zl-trace-build --target "$PWD"
常见失败示例: 常见失败：目标项目未初始化或缺少 .planning/。先运行 zl-init --target "$PWD"。
关联命令: zl-verify zl-preflight zl-help-skills
适用场景: 项目接入、日常状态确认和质量闭环。

`zl-trace-query`

追踪矩阵查询

命令物理名: zl-trace-query
命令逻辑名: 追踪矩阵查询
用途: 把验证结果、需求或决策依据、代码影响和测试覆盖写成可追踪证据。
什么时候用: 项目接入、开发循环或完成前检查需要对应状态时。
基本语法: zl-trace-query --target "$PWD" "退款审批"
参数说明: --target <repo>: 指定目标项目目录。
默认行为: 读取本地项目状态并写入对应 .planning/ 报告，不默认执行重刷新。
是否触发 heavy refresh: 否；只做轻量检查、状态读取、报告写入或 workflow 编排。
输出文件 / 报告路径: stdout trace query result
成功示例: zl-trace-query --target "$PWD" "退款审批"
常见失败示例: 常见失败：目标项目未初始化或缺少 .planning/。先运行 zl-init --target "$PWD"。
关联命令: zl-verify zl-preflight zl-help-skills
适用场景: 项目接入、日常状态确认和质量闭环。

`zl-trace-audit`

追踪矩阵审计

命令物理名: zl-trace-audit
命令逻辑名: 追踪矩阵审计
用途: 把验证结果、需求或决策依据、代码影响和测试覆盖写成可追踪证据。
什么时候用: 项目接入、开发循环或完成前检查需要对应状态时。
基本语法: zl-trace-audit --target "$PWD"
参数说明: --target <repo>: 指定目标项目目录。
默认行为: 读取本地项目状态并写入对应 .planning/ 报告，不默认执行重刷新。
是否触发 heavy refresh: 否；只做轻量检查、状态读取、报告写入或 workflow 编排。
输出文件 / 报告路径: .planning/trace/TRACE_AUDIT.md/json
成功示例: zl-trace-audit --target "$PWD"
常见失败示例: 常见失败：目标项目未初始化或缺少 .planning/。先运行 zl-init --target "$PWD"。
关联命令: zl-verify zl-preflight zl-help-skills
适用场景: 项目接入、日常状态确认和质量闭环。

`zl-evidence-record`

证据记录

命令物理名: zl-evidence-record
命令逻辑名: 证据记录
用途: 把验证结果、需求或决策依据、代码影响和测试覆盖写成可追踪证据。
什么时候用: 项目接入、开发循环或完成前检查需要对应状态时。
基本语法: zl-evidence-record --target "$PWD" "退款审批上限修复已验证" --command "npm test" --result "passed" --writeback .planning/issues/CR-017.md
参数说明: --target <repo>: 指定目标项目目录。
--command <cmd>: 记录验证命令。
--result <text>: 记录验证结果。
--source <paths>: 记录依据来源。
--writeback <file>: 回写到工作记录。
默认行为: 读取本地项目状态并写入对应 .planning/ 报告，不默认执行重刷新。
是否触发 heavy refresh: 否；只做轻量检查、状态读取、报告写入或 workflow 编排。
输出文件 / 报告路径: .planning/evidence/*.md, .planning/evidence/INDEX.md, 可选 writeback
成功示例: zl-evidence-record --target "$PWD" "退款审批上限修复已验证" --command "npm test" --result "passed" --writeback .planning/issues/CR-017.md
常见失败示例: 常见失败：目标项目未初始化或缺少 .planning/。先运行 zl-init --target "$PWD"。
关联命令: zl-verify zl-preflight zl-help-skills
适用场景: 项目接入、日常状态确认和质量闭环。

`zl-evidence-status`

证据状态

命令物理名: zl-evidence-status
命令逻辑名: 证据状态
用途: 把验证结果、需求或决策依据、代码影响和测试覆盖写成可追踪证据。
什么时候用: 项目接入、开发循环或完成前检查需要对应状态时。
基本语法: zl-evidence-status --target "$PWD"
参数说明: --target <repo>: 指定目标项目目录。
默认行为: 读取本地项目状态并写入对应 .planning/ 报告，不默认执行重刷新。
是否触发 heavy refresh: 否；只做轻量检查、状态读取、报告写入或 workflow 编排。
输出文件 / 报告路径: .planning/evidence/INDEX.md 和 stdout summary
成功示例: zl-evidence-status --target "$PWD"
常见失败示例: 常见失败：目标项目未初始化或缺少 .planning/。先运行 zl-init --target "$PWD"。
关联命令: zl-verify zl-preflight zl-help-skills
适用场景: 项目接入、日常状态确认和质量闭环。

`zl-policy-list`

策略列表

命令物理名: zl-policy-list
命令逻辑名: 策略列表
用途: 锁定并验证 local-only、offline、policy 和 license 风险边界。
什么时候用: 保密项目、交付前、或 .planning/config.json 有变更后。
基本语法: zl-policy-list --target "$PWD"
参数说明: --target <repo>: 指定目标项目目录。
--strict: 以严格 profile 语义处理失败。
默认行为: 只做轻量 policy/privacy/preflight/citation/freshness 检查，不触发 GraphRAG index 或 Graphify build。
是否触发 heavy refresh: 否；只做轻量检查、状态读取、报告写入或 workflow 编排。
输出文件 / 报告路径: .planning/policies/POLICY_LIST.md
成功示例: zl-policy-list --target "$PWD"
常见失败示例: 常见失败：offline lock 缺失、配置漂移、外部 provider、API key 形态或 stale 在 strict profile 下被阻断。
关联命令: zl-offline-lock zl-privacy-audit zl-policy-lock zl-policy-verify zl-policy-diff
适用场景: 保密项目、交付前检查、外发风险审计。

`zl-policy-check`

策略检查

命令物理名: zl-policy-check
命令逻辑名: 策略检查
用途: 锁定并验证 local-only、offline、policy 和 license 风险边界。
什么时候用: 保密项目、交付前、或 .planning/config.json 有变更后。
基本语法: zl-policy-check --target "$PWD"
参数说明: --target <repo>: 指定目标项目目录。
--strict: 以严格 profile 语义处理失败。
默认行为: 只做轻量 policy/privacy/preflight/citation/freshness 检查，不触发 GraphRAG index 或 Graphify build。
是否触发 heavy refresh: 否；只做轻量检查、状态读取、报告写入或 workflow 编排。
输出文件 / 报告路径: .planning/policies/POLICY_CHECK.md/json
成功示例: zl-policy-check --target "$PWD"
常见失败示例: 常见失败：offline lock 缺失、配置漂移、外部 provider、API key 形态或 stale 在 strict profile 下被阻断。
关联命令: zl-offline-lock zl-privacy-audit zl-policy-lock zl-policy-verify zl-policy-diff
适用场景: 保密项目、交付前检查、外发风险审计。

`zl-policy-explain`

策略解释

命令物理名: zl-policy-explain
命令逻辑名: 策略解释
用途: 锁定并验证 local-only、offline、policy 和 license 风险边界。
什么时候用: 保密项目、交付前、或 .planning/config.json 有变更后。
基本语法: zl-policy-explain --target "$PWD" privacy.local_only
参数说明: --target <repo>: 指定目标项目目录。
--strict: 以严格 profile 语义处理失败。
默认行为: 只做轻量 policy/privacy/preflight/citation/freshness 检查，不触发 GraphRAG index 或 Graphify build。
是否触发 heavy refresh: 否；只做轻量检查、状态读取、报告写入或 workflow 编排。
输出文件 / 报告路径: .planning/policies/POLICY_EXPLAIN.md
成功示例: zl-policy-explain --target "$PWD" privacy.local_only
常见失败示例: 常见失败：offline lock 缺失、配置漂移、外部 provider、API key 形态或 stale 在 strict profile 下被阻断。
关联命令: zl-offline-lock zl-privacy-audit zl-policy-lock zl-policy-verify zl-policy-diff
适用场景: 保密项目、交付前检查、外发风险审计。

`zl-policy-lock`

策略快照锁定

命令物理名: zl-policy-lock
命令逻辑名: 策略快照锁定
用途: 锁定并验证 local-only、offline、policy 和 license 风险边界。
什么时候用: 保密项目、交付前、或 .planning/config.json 有变更后。
基本语法: zl-offline-lock --target "$PWD" zl-policy-lock --target "$PWD"
参数说明: --target <repo>: 指定目标项目目录。
--strict: 以严格 profile 语义处理失败。
默认行为: 只做轻量 policy/privacy/preflight/citation/freshness 检查，不触发 GraphRAG index 或 Graphify build。
是否触发 heavy refresh: 否；只做轻量检查、状态读取、报告写入或 workflow 编排。
输出文件 / 报告路径: .planning/policies/POLICY_LOCK.md/json
成功示例: zl-offline-lock --target "$PWD" zl-policy-lock --target "$PWD"
常见失败示例: 常见失败：offline lock 缺失、配置漂移、外部 provider、API key 形态或 stale 在 strict profile 下被阻断。
关联命令: zl-offline-lock zl-privacy-audit zl-policy-lock zl-policy-verify zl-policy-diff
适用场景: 保密项目、交付前检查、外发风险审计。

`zl-policy-verify`

策略锁验证

命令物理名: zl-policy-verify
命令逻辑名: 策略锁验证
用途: 锁定并验证 local-only、offline、policy 和 license 风险边界。
什么时候用: 保密项目、交付前、或 .planning/config.json 有变更后。
基本语法: zl-policy-verify --target "$PWD"
参数说明: --target <repo>: 指定目标项目目录。
--strict: 以严格 profile 语义处理失败。
默认行为: 只做轻量 policy/privacy/preflight/citation/freshness 检查，不触发 GraphRAG index 或 Graphify build。
是否触发 heavy refresh: 否；只做轻量检查、状态读取、报告写入或 workflow 编排。
输出文件 / 报告路径: .planning/policies/POLICY_VERIFY.md/json
成功示例: zl-policy-verify --target "$PWD"
常见失败示例: 常见失败：offline lock 缺失、配置漂移、外部 provider、API key 形态或 stale 在 strict profile 下被阻断。
关联命令: zl-offline-lock zl-privacy-audit zl-policy-lock zl-policy-verify zl-policy-diff
适用场景: 保密项目、交付前检查、外发风险审计。

`zl-policy-diff`

策略漂移差分

命令物理名: zl-policy-diff
命令逻辑名: 策略漂移差分
用途: 锁定并验证 local-only、offline、policy 和 license 风险边界。
什么时候用: 保密项目、交付前、或 .planning/config.json 有变更后。
基本语法: zl-policy-diff --target "$PWD"
参数说明: --target <repo>: 指定目标项目目录。
--strict: 以严格 profile 语义处理失败。
默认行为: 只做轻量 policy/privacy/preflight/citation/freshness 检查，不触发 GraphRAG index 或 Graphify build。
是否触发 heavy refresh: 否；只做轻量检查、状态读取、报告写入或 workflow 编排。
输出文件 / 报告路径: .planning/policies/POLICY_DIFF.md/json
成功示例: zl-policy-diff --target "$PWD"
常见失败示例: 常见失败：offline lock 缺失、配置漂移、外部 provider、API key 形态或 stale 在 strict profile 下被阻断。
关联命令: zl-offline-lock zl-privacy-audit zl-policy-lock zl-policy-verify zl-policy-diff
适用场景: 保密项目、交付前检查、外发风险审计。

`zl-privacy-audit`

本地隐私审计

命令物理名: zl-privacy-audit
命令逻辑名: 本地隐私审计
用途: 锁定并验证 local-only、offline、policy 和 license 风险边界。
什么时候用: 项目接入、开发循环或完成前检查需要对应状态时。
基本语法: zl-privacy-audit --target "$PWD" --strict
参数说明: --target <repo>: 指定目标项目目录。
--strict: 以严格 profile 语义处理失败。
默认行为: 读取本地项目状态并写入对应 .planning/ 报告，不默认执行重刷新。
是否触发 heavy refresh: 否；只做轻量检查、状态读取、报告写入或 workflow 编排。
输出文件 / 报告路径: .planning/knowledge/PRIVACY_AUDIT.md
成功示例: zl-privacy-audit --target "$PWD" --strict
常见失败示例: 常见失败：目标项目未初始化或缺少 .planning/。先运行 zl-init --target "$PWD"。
关联命令: zl-offline-lock zl-privacy-audit zl-policy-lock zl-policy-verify zl-policy-diff
适用场景: 保密项目、交付前检查、外发风险审计。

`zl-offline-lock`

离线锁定

命令物理名: zl-offline-lock
命令逻辑名: 离线锁定
用途: 锁定并验证 local-only、offline、policy 和 license 风险边界。
什么时候用: 项目接入、开发循环或完成前检查需要对应状态时。
基本语法: zl-offline-lock --target "$PWD"
参数说明: --target <repo>: 指定目标项目目录。
默认行为: 读取本地项目状态并写入对应 .planning/ 报告，不默认执行重刷新。
是否触发 heavy refresh: 否；只做轻量检查、状态读取、报告写入或 workflow 编排。
输出文件 / 报告路径: .planning/privacy/OFFLINE_LOCK.md/json
成功示例: zl-offline-lock --target "$PWD"
常见失败示例: 常见失败：目标项目未初始化或缺少 .planning/。先运行 zl-init --target "$PWD"。
关联命令: zl-offline-lock zl-privacy-audit zl-policy-lock zl-policy-verify zl-policy-diff
适用场景: 保密项目、交付前检查、外发风险审计。

`zl-outbound-audit`

外发风险审计

命令物理名: zl-outbound-audit
命令逻辑名: 外发风险审计
用途: 锁定并验证 local-only、offline、policy 和 license 风险边界。
什么时候用: 项目接入、开发循环或完成前检查需要对应状态时。
基本语法: zl-outbound-audit --target "$PWD"
参数说明: --target <repo>: 指定目标项目目录。
默认行为: 读取本地项目状态并写入对应 .planning/ 报告，不默认执行重刷新。
是否触发 heavy refresh: 否；只做轻量检查、状态读取、报告写入或 workflow 编排。
输出文件 / 报告路径: .planning/privacy/OUTBOUND_AUDIT.md/json
成功示例: zl-outbound-audit --target "$PWD"
常见失败示例: 常见失败：目标项目未初始化或缺少 .planning/。先运行 zl-init --target "$PWD"。
关联命令: zl-verify zl-preflight zl-help-skills
适用场景: 项目接入、日常状态确认和质量闭环。

`zl-license-audit`

License 风险审计

命令物理名: zl-license-audit
命令逻辑名: License 风险审计
用途: 锁定并验证 local-only、offline、policy 和 license 风险边界。
什么时候用: 项目接入、开发循环或完成前检查需要对应状态时。
基本语法: zl-license-audit --target "$PWD"
参数说明: --target <repo>: 指定目标项目目录。
默认行为: 读取本地项目状态并写入对应 .planning/ 报告，不默认执行重刷新。
是否触发 heavy refresh: 否；只做轻量检查、状态读取、报告写入或 workflow 编排。
输出文件 / 报告路径: verification/reports/license-audit.md 或 .planning/license-audit.md
成功示例: zl-license-audit --target "$PWD"
常见失败示例: 常见失败：目标项目未初始化或缺少 .planning/。先运行 zl-init --target "$PWD"。
关联命令: zl-verify zl-preflight zl-help-skills
适用场景: 项目接入、日常状态确认和质量闭环。

`zl-runtime-install`

Runtime command pack 安装

命令物理名: zl-runtime-install
命令逻辑名: Runtime command pack 安装
用途: 让 Codex、Claude Code、GitHub Copilot 能通过同一套 Zhulong 命令工作。
什么时候用: 需要在 Codex、Claude Code、GitHub Copilot 中调用 Zhulong skills/prompts 时。
基本语法: zl-runtime-install --runtime codex --dest ~/.codex/skills
参数说明: --runtime codex|claude-code|github-copilot: 目标 runtime。
--dest <dir>: 安装或检查目录。
--force: 安装时覆盖已有文件。
默认行为: 读取本地项目状态并写入对应 .planning/ 报告，不默认执行重刷新。
是否触发 heavy refresh: 否；只做轻量检查、状态读取、报告写入或 workflow 编排。
输出文件 / 报告路径: Codex/Claude Code skills 或 GitHub Copilot prompts
成功示例: zl-runtime-install --runtime codex --dest ~/.codex/skills
常见失败示例: 常见失败：目标目录缺文件或模板未渲染。重跑 install 并检查 runtime status。
关联命令: zl-runtime-install zl-runtime-status zl-help-skills
适用场景: 项目接入、日常状态确认和质量闭环。

`zl-runtime-status`

Runtime command pack 状态

命令物理名: zl-runtime-status
命令逻辑名: Runtime command pack 状态
用途: 让 Codex、Claude Code、GitHub Copilot 能通过同一套 Zhulong 命令工作。
什么时候用: 需要在 Codex、Claude Code、GitHub Copilot 中调用 Zhulong skills/prompts 时。
基本语法: zl-runtime-status --runtime codex --dest ~/.codex/skills
参数说明: --runtime codex|claude-code|github-copilot: 目标 runtime。
--dest <dir>: 安装或检查目录。
--force: 安装时覆盖已有文件。
默认行为: 读取本地项目状态并写入对应 .planning/ 报告，不默认执行重刷新。
是否触发 heavy refresh: 否；只做轻量检查、状态读取、报告写入或 workflow 编排。
输出文件 / 报告路径: stdout runtime pack 渲染状态
成功示例: zl-runtime-status --runtime codex --dest ~/.codex/skills
常见失败示例: 常见失败：目标目录缺文件或模板未渲染。重跑 install 并检查 runtime status。
关联命令: zl-runtime-install zl-runtime-status zl-help-skills
适用场景: 项目接入、日常状态确认和质量闭环。

`zl-context-debug`

Debug 上下文包

命令物理名: zl-context-debug
命令逻辑名: Debug 上下文包
用途: 让 Codex、Claude Code、GitHub Copilot 能通过同一套 Zhulong 命令工作。
什么时候用: 项目接入、开发循环或完成前检查需要对应状态时。
基本语法: zl-context-debug --target "$PWD" "退款上限与业务规则不一致"
参数说明: --target <repo>: 指定目标项目目录。
默认行为: 读取本地项目状态并写入对应 .planning/ 报告，不默认执行重刷新。
是否触发 heavy refresh: 否；只做轻量检查、状态读取、报告写入或 workflow 编排。
输出文件 / 报告路径: .planning/context/*debug*.md 和 handoff
成功示例: zl-context-debug --target "$PWD" "退款上限与业务规则不一致"
常见失败示例: 常见失败：目标项目未初始化或缺少 .planning/。先运行 zl-init --target "$PWD"。
关联命令: zl-verify zl-preflight zl-help-skills
适用场景: 项目接入、日常状态确认和质量闭环。

`zl-context-execute`

实施上下文包

命令物理名: zl-context-execute
命令逻辑名: 实施上下文包
用途: 让 Codex、Claude Code、GitHub Copilot 能通过同一套 Zhulong 命令工作。
什么时候用: 项目接入、开发循环或完成前检查需要对应状态时。
基本语法: zl-context-execute --target "$PWD" "实现退款上限检查"
参数说明: --target <repo>: 指定目标项目目录。
默认行为: 读取本地项目状态并写入对应 .planning/ 报告，不默认执行重刷新。
是否触发 heavy refresh: 否；只做轻量检查、状态读取、报告写入或 workflow 编排。
输出文件 / 报告路径: .planning/context/*execute*.md 和 handoff
成功示例: zl-context-execute --target "$PWD" "实现退款上限检查"
常见失败示例: 常见失败：目标项目未初始化或缺少 .planning/。先运行 zl-init --target "$PWD"。
关联命令: zl-verify zl-preflight zl-help-skills
适用场景: 项目接入、日常状态确认和质量闭环。

`zl-new-milestone`

开启里程碑循环

命令物理名: zl-new-milestone
命令逻辑名: 开启里程碑循环
用途: 面向日常开发的公开工作流入口，内部会写 context、handoff、workflow facade 和 gate 状态。
什么时候用: 日常改修、新规开发、缺陷调查、审查、验证和收口时。
基本语法: zl-new-milestone --target "$PWD" "当前任务说明"
参数说明: --target <repo>: 指定目标项目目录。
默认行为: 启动当前 guarded workflow，写 context/handoff/facade，并输出 heavy refresh executed: no；不自动调用建议的下一 Skill。
是否触发 heavy refresh: 否；只做轻量检查、状态读取、报告写入或 workflow 编排。
输出文件 / 报告路径: .planning/context/*, .planning/context/handoffs/*, .planning/workflows/<id>/WORKFLOW_FACADE.md/json
成功示例: zl-new-milestone --target "$PWD" "当前任务说明"
常见失败示例: 常见失败：目标项目未初始化或缺少 .planning/。先运行 zl-init --target "$PWD"。
关联命令: zl-workflow-status zl-workflow-audit zl-evidence-record zl-completion-check
适用场景: 从需求、调查、计划、实施、验证到完成的开发主循环。

`zl-spec-phase`

需求整理阶段

命令物理名: zl-spec-phase
命令逻辑名: 需求整理阶段
用途: 面向日常开发的公开工作流入口，内部会写 context、handoff、workflow facade 和 gate 状态。
什么时候用: 日常改修、新规开发、缺陷调查、审查、验证和收口时。
基本语法: zl-spec-phase --target "$PWD" "当前任务说明"
参数说明: --target <repo>: 指定目标项目目录。
默认行为: 启动当前 guarded workflow，写 context/handoff/facade，并输出 heavy refresh executed: no；不自动调用建议的下一 Skill。
是否触发 heavy refresh: 否；只做轻量检查、状态读取、报告写入或 workflow 编排。
输出文件 / 报告路径: .planning/context/*, .planning/context/handoffs/*, .planning/workflows/<id>/WORKFLOW_FACADE.md/json
成功示例: zl-spec-phase --target "$PWD" "当前任务说明"
常见失败示例: 常见失败：目标项目未初始化或缺少 .planning/。先运行 zl-init --target "$PWD"。
关联命令: zl-workflow-status zl-workflow-audit zl-evidence-record zl-completion-check
适用场景: 从需求、调查、计划、实施、验证到完成的开发主循环。

`zl-discuss-phase`

讨论决策阶段

命令物理名: zl-discuss-phase
命令逻辑名: 讨论决策阶段
用途: 面向日常开发的公开工作流入口，内部会写 context、handoff、workflow facade 和 gate 状态。
什么时候用: 日常改修、新规开发、缺陷调查、审查、验证和收口时。
基本语法: zl-discuss-phase --target "$PWD" "当前任务说明"
参数说明: --target <repo>: 指定目标项目目录。
默认行为: 启动当前 guarded workflow，写 context/handoff/facade，并输出 heavy refresh executed: no；不自动调用建议的下一 Skill。
是否触发 heavy refresh: 否；只做轻量检查、状态读取、报告写入或 workflow 编排。
输出文件 / 报告路径: .planning/context/*, .planning/context/handoffs/*, .planning/workflows/<id>/WORKFLOW_FACADE.md/json
成功示例: zl-discuss-phase --target "$PWD" "当前任务说明"
常见失败示例: 常见失败：目标项目未初始化或缺少 .planning/。先运行 zl-init --target "$PWD"。
关联命令: zl-workflow-status zl-workflow-audit zl-evidence-record zl-completion-check
适用场景: 从需求、调查、计划、实施、验证到完成的开发主循环。

`zl-ui-phase`

UI 范围阶段

命令物理名: zl-ui-phase
命令逻辑名: UI 范围阶段
用途: 读取项目设计证据，定义 UI 状态与数据合同，并在 preserve、evolve、create、system 间选择条件化 Taste 权限。
什么时候用: 创建前端、自然演进、重设计或修改既有 UI 前；必须先确定是否继承现有设计以及 Taste 的权限。
基本语法: zl-ui-phase --target "$PWD" "当前任务说明"
参数说明: --target <repo>: 指定目标项目目录。
默认行为: 默认读取 manifest、依赖、设计资料、token、组件和现有页面，生成 Frontend Design Decision；不自动安装 Taste，不改变既有设计，不触发 heavy refresh。
是否触发 heavy refresh: 否；只做轻量检查、状态读取、报告写入或 workflow 编排。
输出文件 / 报告路径: .planning/context/*, .planning/context/handoffs/*, .planning/workflows/<id>/WORKFLOW_FACADE.md/json
成功示例: zl-ui-phase --target "$PWD" "当前任务说明"
常见失败示例: 常见失败：缺少足以区分 preserve/evolve/create/system 的设计证据。只有模式差异会实质影响结果时才询问一个设计方向问题。
关联命令: zl-workflow-status zl-workflow-audit zl-evidence-record zl-completion-check
适用场景: greenfield 营销页、自然演进前端、既存设计维护、Dashboard 与管理后台的设计权限路由。

`zl-debug`

缺陷调查工作流

命令物理名: zl-debug
命令逻辑名: 缺陷调查工作流
用途: 默认只调查和验证根因；只有用户明确要求修复，或当前 milestone 有匹配的 debug_fix Goal 授权时才实施。
什么时候用: 日常改修、新规开发、缺陷调查、审查、验证和收口时。
基本语法: zl-debug --target "$PWD" "当前任务说明"
参数说明: --target <repo>: 指定目标项目目录。
默认行为: 默认 requestIntent=diagnose-only，不要求也不允许 implementation gate；显式 fix 或匹配 Goal 后才进入实施。
是否触发 heavy refresh: 否；只做轻量检查、状态读取、报告写入或 workflow 编排。
输出文件 / 报告路径: .planning/context/*, .planning/context/handoffs/*, .planning/workflows/<id>/WORKFLOW_FACADE.md/json
成功示例: zl-debug --target "$PWD" "当前任务说明"
常见失败示例: 常见失败：目标项目未初始化或缺少 .planning/。先运行 zl-init --target "$PWD"。
关联命令: zl-workflow-status zl-workflow-audit zl-evidence-record zl-completion-check
适用场景: 从需求、调查、计划、实施、验证到完成的开发主循环。

`zl-plan-phase`

计划阶段

命令物理名: zl-plan-phase
命令逻辑名: 计划阶段
用途: 面向日常开发的公开工作流入口，内部会写 context、handoff、workflow facade 和 gate 状态。
什么时候用: 日常改修、新规开发、缺陷调查、审查、验证和收口时。
基本语法: zl-plan-phase --target "$PWD" "当前任务说明"
参数说明: --target <repo>: 指定目标项目目录。
默认行为: 启动当前 guarded workflow，写 context/handoff/facade，并输出 heavy refresh executed: no；不自动调用建议的下一 Skill。
是否触发 heavy refresh: 否；只做轻量检查、状态读取、报告写入或 workflow 编排。
输出文件 / 报告路径: .planning/context/*, .planning/context/handoffs/*, .planning/workflows/<id>/WORKFLOW_FACADE.md/json
成功示例: zl-plan-phase --target "$PWD" "当前任务说明"
常见失败示例: 常见失败：目标项目未初始化或缺少 .planning/。先运行 zl-init --target "$PWD"。
关联命令: zl-workflow-status zl-workflow-audit zl-evidence-record zl-completion-check
适用场景: 从需求、调查、计划、实施、验证到完成的开发主循环。

`zl-execute-phase`

实施阶段

命令物理名: zl-execute-phase
命令逻辑名: 实施阶段
用途: 面向日常开发的公开工作流入口，内部会写 context、handoff、workflow facade 和 gate 状态。
什么时候用: 日常改修、新规开发、缺陷调查、审查、验证和收口时。
基本语法: zl-execute-phase --target "$PWD" "当前任务说明"
参数说明: --target <repo>: 指定目标项目目录。
默认行为: 启动当前 guarded workflow，写 context/handoff/facade，并输出 heavy refresh executed: no；不自动调用建议的下一 Skill。
是否触发 heavy refresh: 否；只做轻量检查、状态读取、报告写入或 workflow 编排。
输出文件 / 报告路径: .planning/context/*, .planning/context/handoffs/*, .planning/workflows/<id>/WORKFLOW_FACADE.md/json
成功示例: zl-execute-phase --target "$PWD" "当前任务说明"
常见失败示例: 常见失败：目标项目未初始化或缺少 .planning/。先运行 zl-init --target "$PWD"。
关联命令: zl-workflow-status zl-workflow-audit zl-evidence-record zl-completion-check
适用场景: 从需求、调查、计划、实施、验证到完成的开发主循环。

`zl-code-review`

代码审查工作流

命令物理名: zl-code-review
命令逻辑名: 代码审查工作流
用途: 面向日常开发的公开工作流入口，内部会写 context、handoff、workflow facade 和 gate 状态。
什么时候用: 日常改修、新规开发、缺陷调查、审查、验证和收口时。
基本语法: zl-code-review --target "$PWD" "当前任务说明"
参数说明: --target <repo>: 指定目标项目目录。
默认行为: 启动当前 guarded workflow，写 context/handoff/facade，并输出 heavy refresh executed: no；不自动调用建议的下一 Skill。
是否触发 heavy refresh: 否；只做轻量检查、状态读取、报告写入或 workflow 编排。
输出文件 / 报告路径: .planning/context/*, .planning/context/handoffs/*, .planning/workflows/<id>/WORKFLOW_FACADE.md/json
成功示例: zl-code-review --target "$PWD" "当前任务说明"
常见失败示例: 常见失败：目标项目未初始化或缺少 .planning/。先运行 zl-init --target "$PWD"。
关联命令: zl-workflow-status zl-workflow-audit zl-evidence-record zl-completion-check
适用场景: 从需求、调查、计划、实施、验证到完成的开发主循环。

`zl-verify-work`

工作验证阶段

命令物理名: zl-verify-work
命令逻辑名: 工作验证阶段
用途: 面向日常开发的公开工作流入口，内部会写 context、handoff、workflow facade 和 gate 状态。
什么时候用: 日常改修、新规开发、缺陷调查、审查、验证和收口时。
基本语法: zl-verify-work --target "$PWD" "当前任务说明"
参数说明: --target <repo>: 指定目标项目目录。
默认行为: 启动当前 guarded workflow，写 context/handoff/facade，并输出 heavy refresh executed: no；不自动调用建议的下一 Skill。
是否触发 heavy refresh: 否；只做轻量检查、状态读取、报告写入或 workflow 编排。
输出文件 / 报告路径: .planning/context/*, .planning/context/handoffs/*, .planning/workflows/<id>/WORKFLOW_FACADE.md/json
成功示例: zl-verify-work --target "$PWD" "当前任务说明"
常见失败示例: 常见失败：目标项目未初始化或缺少 .planning/。先运行 zl-init --target "$PWD"。
关联命令: zl-workflow-status zl-workflow-audit zl-evidence-record zl-completion-check
适用场景: 从需求、调查、计划、实施、验证到完成的开发主循环。

`zl-complete-milestone`

完成里程碑

命令物理名: zl-complete-milestone
命令逻辑名: 完成里程碑
用途: 面向日常开发的公开工作流入口，内部会写 context、handoff、workflow facade 和 gate 状态。
什么时候用: 日常改修、新规开发、缺陷调查、审查、验证和收口时。
基本语法: zl-complete-milestone --target "$PWD" "当前任务说明"
参数说明: --target <repo>: 指定目标项目目录。
默认行为: 启动当前 guarded workflow，写 context/handoff/facade，并输出 heavy refresh executed: no；不自动调用建议的下一 Skill。
是否触发 heavy refresh: 否；只做轻量检查、状态读取、报告写入或 workflow 编排。
输出文件 / 报告路径: .planning/context/*, .planning/context/handoffs/*, .planning/workflows/<id>/WORKFLOW_FACADE.md/json
成功示例: zl-complete-milestone --target "$PWD" "当前任务说明"
常见失败示例: 常见失败：目标项目未初始化或缺少 .planning/。先运行 zl-init --target "$PWD"。
关联命令: zl-workflow-status zl-workflow-audit zl-evidence-record zl-completion-check
适用场景: 从需求、调查、计划、实施、验证到完成的开发主循环。

`zl-workflow-run`

通用 workflow 启动

命令物理名: zl-workflow-run
命令逻辑名: 通用 workflow 启动
用途: 检查当前工作授权、结果验收或 Goal、结构化决策、类型化 plan/implementation/verification、绑定 evidence/writeback 等完成条件。
什么时候用: 需要调试、恢复或审计当前 workflow gate 时。
基本语法: zl-workflow-run --target "$PWD" debug "生产审批金额异常" --source user-message zl-workflow-run --target "$PWD" execute-phase "<contract objective>" --authorization <id> --milestone MVP4.1 --contract-digest <digest>
参数说明: --target <repo>: 指定目标项目目录。
--source user-message: 仅由 runtime 在 Skill 直接响应当前用户消息时附加；alias 不会自动推断来源。
--accept-completion: 只有原始消息明确要求完成/关闭时使用；否则等待后续用户验收。
--authorization <id> --milestone <name> --contract-digest <digest>: Goal child 必须携带的结构化授权上下文，并使用合同中的精确 objective。
--intent fix: debug 仅在用户明确要求修复时使用；默认 diagnose-only。
默认行为: 读取本地项目状态并写入对应 .planning/ 报告，不默认执行重刷新。
是否触发 heavy refresh: 否；只做轻量检查、状态读取、报告写入或 workflow 编排。
输出文件 / 报告路径: .planning/workflows/<id>/WORKFLOW_STATE.md/json, WORKFLOW_FACADE.md/json
成功示例: zl-workflow-run --target "$PWD" debug "生产审批金额异常" --source user-message zl-workflow-run --target "$PWD" execute-phase "<contract objective>" --authorization <id> --milestone MVP4.1 --contract-digest <digest>
常见失败示例: 常见失败：缺当前工作授权、缺结果验收或 Goal、存在重大开放决策，或缺当前 workflow 的类型化 artifact、evidence/writeback。按 WORKFLOW_AUDIT.md 补齐；不要用任意字符串或历史文件绕过。
关联命令: zl-workflow-status zl-workflow-audit zl-evidence-record zl-completion-check
适用场景: AI 声称完成前、接手中断任务、或 gate 失败排查。

`zl-workflow-status`

workflow 状态查看

命令物理名: zl-workflow-status
命令逻辑名: workflow 状态查看
用途: 检查当前工作授权、结果验收或 Goal、结构化决策、类型化 plan/implementation/verification、绑定 evidence/writeback 等完成条件。
什么时候用: 需要调试、恢复或审计当前 workflow gate 时。
基本语法: zl-workflow-status --target "$PWD"
参数说明: --target <repo>: 指定目标项目目录。
默认行为: 读取本地项目状态并写入对应 .planning/ 报告，不默认执行重刷新。
是否触发 heavy refresh: 否；只做轻量检查、状态读取、报告写入或 workflow 编排。
输出文件 / 报告路径: stdout gate 状态
成功示例: zl-workflow-status --target "$PWD"
常见失败示例: 常见失败：缺当前工作授权、缺结果验收或 Goal、存在重大开放决策，或缺当前 workflow 的类型化 artifact、evidence/writeback。按 WORKFLOW_AUDIT.md 补齐；不要用任意字符串或历史文件绕过。
关联命令: zl-workflow-status zl-workflow-audit zl-evidence-record zl-completion-check
适用场景: AI 声称完成前、接手中断任务、或 gate 失败排查。

`zl-workflow-continue`

人工 gate 标记

命令物理名: zl-workflow-continue
命令逻辑名: 人工 gate 标记
用途: 检查当前工作授权、结果验收或 Goal、结构化决策、类型化 plan/implementation/verification、绑定 evidence/writeback 等完成条件。
什么时候用: 需要调试、恢复或审计当前 workflow gate 时。
基本语法: zl-workflow-continue --target "$PWD" --gate plan --evidence .planning/workflows/<id>/PLAN.md
参数说明: --target <repo>: 指定目标项目目录。
--gate plan|implementation|verification: 标记当前 workflow 所需 gate。
--evidence <path>: 当前 workflow 的类型化证据文件；不接受任意字符串。
默认行为: 读取本地项目状态并写入对应 .planning/ 报告，不默认执行重刷新。
是否触发 heavy refresh: 否；只做轻量检查、状态读取、报告写入或 workflow 编排。
输出文件 / 报告路径: .planning/workflows/<id>/WORKFLOW_STATE.md/json
成功示例: zl-workflow-continue --target "$PWD" --gate plan --evidence .planning/workflows/<id>/PLAN.md
常见失败示例: 常见失败：缺当前工作授权、缺结果验收或 Goal、存在重大开放决策，或缺当前 workflow 的类型化 artifact、evidence/writeback。按 WORKFLOW_AUDIT.md 补齐；不要用任意字符串或历史文件绕过。
关联命令: zl-workflow-status zl-workflow-audit zl-evidence-record zl-completion-check
适用场景: AI 声称完成前、接手中断任务、或 gate 失败排查。

`zl-workflow-audit`

workflow 审计

命令物理名: zl-workflow-audit
命令逻辑名: workflow 审计
用途: 检查当前工作授权、结果验收或 Goal、结构化决策、类型化 plan/implementation/verification、绑定 evidence/writeback 等完成条件。
什么时候用: 需要调试、恢复或审计当前 workflow gate 时。
基本语法: zl-workflow-audit --target "$PWD"
参数说明: --target <repo>: 指定目标项目目录。
默认行为: 读取本地项目状态并写入对应 .planning/ 报告，不默认执行重刷新。
是否触发 heavy refresh: 否；只做轻量检查、状态读取、报告写入或 workflow 编排。
输出文件 / 报告路径: .planning/workflows/<id>/WORKFLOW_AUDIT.md
成功示例: zl-workflow-audit --target "$PWD"
常见失败示例: 常见失败：缺当前工作授权、缺结果验收或 Goal、存在重大开放决策，或缺当前 workflow 的类型化 artifact、evidence/writeback。按 WORKFLOW_AUDIT.md 补齐；不要用任意字符串或历史文件绕过。
关联命令: zl-workflow-status zl-workflow-audit zl-evidence-record zl-completion-check
适用场景: AI 声称完成前、接手中断任务、或 gate 失败排查。

`zl-gate-check`

gate 检查

命令物理名: zl-gate-check
命令逻辑名: gate 检查
用途: 检查当前工作授权、结果验收或 Goal、结构化决策、类型化 plan/implementation/verification、绑定 evidence/writeback 等完成条件。
什么时候用: 需要调试、恢复或审计当前 workflow gate 时。
基本语法: zl-gate-check --target "$PWD"
参数说明: --target <repo>: 指定目标项目目录。
默认行为: 读取本地项目状态并写入对应 .planning/ 报告，不默认执行重刷新。
是否触发 heavy refresh: 否；只做轻量检查、状态读取、报告写入或 workflow 编排。
输出文件 / 报告路径: stdout gate result
成功示例: zl-gate-check --target "$PWD"
常见失败示例: 常见失败：缺当前工作授权、缺结果验收或 Goal、存在重大开放决策，或缺当前 workflow 的类型化 artifact、evidence/writeback。按 WORKFLOW_AUDIT.md 补齐；不要用任意字符串或历史文件绕过。
关联命令: zl-workflow-status zl-workflow-audit zl-evidence-record zl-completion-check
适用场景: AI 声称完成前、接手中断任务、或 gate 失败排查。

`zl-completion-check`

只读完成资格检查

命令物理名: zl-completion-check
命令逻辑名: 只读完成资格检查
用途: 检查当前工作授权、结果验收或 Goal、结构化决策、类型化 plan/implementation/verification、绑定 evidence/writeback 等完成条件。
什么时候用: AI 或开发者准备声明任务完成前；本命令只检查资格，不会写入 complete。
基本语法: zl-completion-check --target "$PWD"
参数说明: --target <repo>: 指定目标项目目录。
默认行为: 只刷新 gate/structure 审计并输出 completion eligible 或 blocked；不会写 complete。
是否触发 heavy refresh: 否；只做轻量检查、状态读取、报告写入或 workflow 编排。
输出文件 / 报告路径: stdout completion eligible/blocked（不修改状态）
成功示例: zl-completion-check --target "$PWD"
常见失败示例: 常见失败：缺当前工作授权、缺结果验收或 Goal、存在重大开放决策，或缺当前 workflow 的类型化 artifact、evidence/writeback。按 WORKFLOW_AUDIT.md 补齐；不要用任意字符串或历史文件绕过。
关联命令: zl-workflow-status zl-workflow-audit zl-evidence-record zl-completion-check
适用场景: AI 声称完成前、接手中断任务、或 gate 失败排查。

`zl-cockpit-build`

项目驾驶舱生成

命令物理名: zl-cockpit-build
命令逻辑名: 项目驾驶舱生成
用途: 把 Graphify、GraphRAG/RAG、workflow、quality、privacy 和 evidence 状态聚合成本地静态驾驶舱。
什么时候用: 需要给自己或 leader 看项目健康度、Graphify 影响面、RAG 证据链和质量闭环状态时。
基本语法: zl-cockpit-build --target "$PWD"
参数说明: --target <repo>: 指定目标项目目录。
默认行为: 读取 templates/cockpit/index.template.html，注入目标项目的本地 cockpit-data.json 和稳定 cockpit-viewmodel.v1，生成带搜索、节点详情、legend 过滤和大图聚合的静态 HTML；默认不联网、不调用外部 LLM、不刷新 Graphify/RAG。稳定展示样例见 templates/cockpit/sample.html。
是否触发 heavy refresh: 否；只读取已有本地 artifact，生成静态 HTML，不执行 GraphRAG index 或 Graphify build。
输出文件 / 报告路径: .planning/cockpit/index.html, cockpit-data.json, COCKPIT_REPORT.md, assets/
成功示例: zl-cockpit-build --target "$PWD"
常见失败示例: 常见失败：真实项目 Graphify/RAG artifact 缺失会显示 WAIVED_WITH_RISK。先看 templates/cockpit/sample.html 确认目标形态；图过大时 cockpit 会自动使用 aggregated-community 预览；需要最新图时显式运行 zl-graph-build --target "$PWD" --run。
关联命令: zl-graph-status zl-docs-sync zl-answer-audit zl-privacy-audit
适用场景: leader 演示、项目状态自查、交付前展示 Graphify/RAG/evidence/quality 状态。

`zl-help-skills`

场景命令推荐

命令物理名: zl-help-skills
命令逻辑名: 场景命令推荐
用途: 根据场景给出下一步 Zhulong 命令建议或状态入口。
什么时候用: 项目接入、开发循环或完成前检查需要对应状态时。
基本语法: zl-help-skills --target "$PWD" "文档更新后确认影响面"
参数说明: --target <repo>: 指定目标项目目录。
默认行为: 读取本地项目状态并写入对应 .planning/ 报告，不默认执行重刷新。
是否触发 heavy refresh: 否；只做轻量检查、状态读取、报告写入或 workflow 编排。
输出文件 / 报告路径: .planning/help/HELP_SKILLS.md/json
成功示例: zl-help-skills --target "$PWD" "文档更新后确认影响面"
常见失败示例: 常见失败：目标项目未初始化或缺少 .planning/。先运行 zl-init --target "$PWD"。
关联命令: zl-verify zl-preflight zl-help-skills
适用场景: 项目接入、日常状态确认和质量闭环。

`zl-next`

下一步命令发现

命令物理名: zl-next
命令逻辑名: 下一步命令发现
用途: 根据场景给出下一步 Zhulong 命令建议或状态入口。
什么时候用: 不知道当前该运行哪条命令，或接手一个已有项目时。
基本语法: zl-next --target "$PWD"
参数说明: --target <repo>: 指定目标项目目录。
默认行为: 只读取本地状态并给出 2-3 条命令，不自动执行建议，也不运行重型刷新。
是否触发 heavy refresh: 否；只做轻量检查、状态读取、报告写入或 workflow 编排。
输出文件 / 报告路径: .planning/help/NEXT.md
成功示例: zl-next --target "$PWD"
常见失败示例: 常见失败：目标项目未初始化或缺少 .planning/。先运行 zl-init --target "$PWD"。
关联命令: zl-verify zl-preflight zl-help-skills
适用场景: 项目接入、日常状态确认和质量闭环。