Zhulong 如何工作。

1. 心智模型

Zhulong 是目标项目旁边的一层本地 intelligence layer。它不搬动源码，不替代 IDE，不替代 AI runtime。它负责组织上下文、证据、代码地图和完成前检查。

普通:
prompt -> 改代码 -> 可能跑测试

Zhulong:
zl command
  -> project state
  -> docs/RAG evidence
  -> Graphify impact
  -> plan / implementation / verification
  -> evidence writeback
  -> completion-check

场景选择模型

Zhulong 是通用项目框架，不要求所有项目启用 RAG。它把 workflow、代码地图、可选文档依据和 evidence 按项目约束组合起来：非文档密集型项目使用专门的 rag none 路线，文档承担需求、验收或合规责任时再启用严格文档和本地 GraphRAG。

2. Zhulong 仓库结构

3. 接入目标项目

Zhulong 接入后会在目标项目根目录增加 AGENTS.md、project.manifest.yml、.planning/。不会移动原来的 src/、tests/、docs/。

target-project/
  src/
  tests/
  docs/
  AGENTS.md
  project.manifest.yml
  .planning/
    PROJECT.md
    STATE.md
    config.json
    codebase/
    knowledge/
    graphs/
    refresh/
    workflows/
    evidence/

zl-init --target "$PWD" --template greenfield-app --name app --mode new --doc-policy reference --rag none
zl-codebase-scan --target "$PWD"

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

4. Workflow guard

Guard 是 Zhulong 当前最核心的“硬约束”。它不是只在 prompt 里提醒 agent，而是检查目标项目中的本地 artifact。

zl-debug --target "$PWD" "bug"
  -> workflow run debug
  -> write .planning/context/debug-*.md
  -> write .planning/context/handoffs/*-HANDOFF.md
  -> write .planning/workflows/<id>/WORKFLOW_STATE.json
  -> evaluate gates
  -> completion eligible / blocked
  -> explicit workflow complete changes state

5. 文档 / RAG 机制

真实终端中只运行 zl-init --target "$PWD" 会进入 init wizard，依次选择项目类型、文档策略、RAG 后端和本地/外部 RAG 风险；CI 和 runtime pack 使用显式参数，避免等待输入。默认的 reference + rag none 专门适配非文档密集型项目：不安装 GraphRAG，不执行 index，也不要求 RAG 参与日常 workflow。文档密集或规格严格项目在 init 时选择 --doc-policy strict --rag local，再显式准备本地 GraphRAG、Ollama 和本地模型。外部 provider 不是默认能力，必须 --allow-external-rag。

python3 --version  # GraphRAG requires Python 3.10-3.12
python3 -m pip install --user graphrag
export PATH="$HOME/.local/bin:$PATH"

brew install ollama
brew services start ollama
ollama pull qwen2.5:7b
ollama pull bge-m3

.planning/config.json
{
  "spec_context": {
    "enabled": true,
    "provider": "graphrag-local",
    "source_paths": ["docs", "documents", "仕様書"],
    "index_command": "graphrag index --root graphrag-workspace --method fast",
    "query_command": "graphrag query --root graphrag-workspace --method basic {query}"
  },
  "graphrag": {
    "enabled": true,
    "mode": "local",
    "profile": "local_basic",
    "requires_api_key": false,
    "llm_model": "qwen2.5:7b",
    "embedding_model": "bge-m3",
    "api_base": "http://127.0.0.1:11434",
    "vector_store": "lancedb"
  }
}

6. Graphify 机制

Zhulong 不重写 Graphify。Zhulong 通过配置执行 Graphify，然后把 graphify-out/ 中的结果同步到 .planning/graphs/，供 workflow guard 和 query 使用。

.planning/config.json
{
  "code_map": {
    "provider": "graphify",
    "update_command": "graphify update ."
  }
}

7. Runtime command pack

Runtime pack 只是让不同 AI 工具知道如何调用 Zhulong。核心命令仍然是本地 zl CLI。

交互默认与有界自动执行

三种 runtime 都读取同一份 core/workflows/authorization.md：默认只执行当前 Skill，“建议下一步”不能触发下一个 workflow；调查、分析、诊断默认 diagnose-only。Workflow alias 不会自动注入用户来源；只有直接响应当前用户消息的 runtime 才能附加 --source user-message，且这只是可审计的 runtime assertion，不是密码学身份认证。用户明确说“自动执行 MVP4.0 到 MVP4.7，完成后停止”时，runtime 把每个 MVP 的原始描述编译成结构化 milestone contract，child workflow 继承 authorization ID、milestone 与 contract digest，并使用合同中的精确 objective。

workflow:
  mode: interactive
  auto_advance: false
  require_explicit_user_intent: true
  allow_goal_authorization: true

zl workflow authorize --target "$PWD" \
  --source user-message \
  --request "自动执行 MVP4.0 到 MVP4.7，完成后停止" \
  --contract-file ".planning/goals/MVP4_CONTRACTS.json" \
  --actions "spec,ui,plan,execute,review,verify,complete_milestone,advance" \
  --stop-after MVP4.7

授权合同保存在 .planning/goals/，可用 zl workflow authorization-status 检查、用 zl workflow revoke 撤销。执行、修复、完成与推进必须使用结构化合同；旧式只有 milestone 名称的 grant 仅能用于非修改型 workflow。依赖、commit、push、merge、release 前还要通过 zl workflow permission-check。范围外 objective、digest、milestone/action、重大 open question 与 contradiction 都会阻塞。

条件化 Taste 前端设计

zl-ui-phase 会读取项目 manifest、依赖和有界的前端路径证据，实际计算并写入 Frontend Design Decision，而不是只输出待填写模板。Runtime 随后补充品牌资料、既有页面和人工设计证据；低置信度只提出一个方向问题。Taste Adapter 已内置，不需要另外运行 npx skills add。

frontend_design:
  strategy: auto       # auto | preserve | evolve | create | system
  taste: auto          # auto | enabled | disabled

优先级固定为：用户明确要求、正式设计与规格证据、合规与可访问性约束、现有源码约定、Taste Adapter、模型自由选择。greenfield 营销页通常进入 create；brownfield 项目只有在风格确实零散时才进入 evolve。设置 taste: disabled 可以完全关闭 Taste。

zl-runtime-install --runtime codex --dest ~/.codex/skills
zl-runtime-install --runtime claude-code --dest ~/.claude/skills
zl-runtime-install --runtime github-copilot --dest .github/prompts
zl-runtime-status --runtime codex --dest ~/.codex/skills

8. Evidence loop

Evidence loop 的原则是：实现不能只停留在聊天记录里，必须写回项目本地 artifact。

zl-evidence-record --target "$PWD" \
  "CR-017 proxy approval limit verified" \
  --command "npm test && npm run test:task" \
  --result "passed" \
  --source "docs/qa/QA-042.md,.planning/graphs/GRAPH_REPORT.md" \
  --writeback .planning/issues/CR-017.md

这会创建 evidence record，并在目标 issue 中追加 Zhulong Evidence Writeback。Guard 的 evidence 和 writeback gate 都依赖它。

9. MVP3 证据质量

MVP3 把“查到了文档”和“有了证据”再往前推一步：RAG 答案要能用 golden case 复跑，citation 要能指向真实源文件，文档、代码、测试和 evidence 要能进入 trace matrix。

zl-rag-golden-add --target "$PWD" \
  --question "代理承認の上限金額は？" \
  --expect "30,000" \
  --citation "docs/qa/QA-042.md:3"

zl-rag-golden-run --target "$PWD"
zl-rag-eval --target "$PWD"
zl-citation-audit --target "$PWD"

zl-trace-build --target "$PWD"
zl-trace-query --target "$PWD" "代理承認"
zl-trace-audit --target "$PWD"

核心产物是 .planning/quality/ 和 .planning/trace/。以后接可视化 QA 时，这两类文件会成为“需求或决策依据 -> 代码影响面 -> 测试 -> evidence”的数据源。

zl-docs-sync --target "$PWD"
zl-docs-query --target "$PWD" "代理承認 上限"
zl-answer-audit --target "$PWD"

# 只有明确需要重建本地 GraphRAG index 时
zl-docs-sync --target "$PWD" --index

zl-preflight --target "$PWD"
zl-refresh-plan --target "$PWD"
zl-refresh-run --target "$PWD" --rag
zl-refresh-run --target "$PWD" --graph
zl-mode-status --target "$PWD"
zl-mode-set --target "$PWD" docs-reference
zl-mode-set --target "$PWD" docs-strict

10. Policy mode

Policy mode 是完成前的横向审计：local-only、citation、golden、trace、graph freshness、license 必须统一给出四态结果。它不是聊天建议，而是写入 .planning/policies/ 的本地报告。

zl-policy-list --target "$PWD"
zl-policy-explain --target "$PWD" privacy.local_only
zl-policy-check --target "$PWD" --strict
zl-policy-lock --target "$PWD"
zl-policy-verify --target "$PWD"
zl-policy-diff --target "$PWD"

zl-policy-lock 生成稳定 snapshot 和 SHA-256 hash；zl-policy-verify 重新生成 snapshot 并做轻量 checks；zl-policy-diff 输出字段级差异。三条命令都必须输出 heavy refresh executed: no，不会触发 GraphRAG index 或 Graphify build。

当你不知道该跑什么命令时，可以用 zl-help-skills 让 Zhulong 根据场景推荐命令组：

zl-help-skills --target "$PWD" "文档更新后想确认影响面和完成前检查"

11. 保密边界

• 审查 .planning/config.json 中的 index_command、query_command、update_command。
• 默认保密项目使用 zl-rag-init-local、Ollama、本地 embedding 和 LanceDB。
• 运行 zl-offline-lock --target "$PWD"、zl-privacy-audit --target "$PWD" --strict、zl-outbound-audit --target "$PWD"，确认没有外部 endpoint、外部 provider、API key 或网络命令。
• 不要把 .planning/、graphify-out/、graphrag-workspace/ 提交到公开仓库。

不要把 graphrag-workspace/settings.yaml 中的 model_provider 改成 openai、deepseek、azure 等外部 provider，也不要把 api_base 改成公网 URL。GraphRAG index 会处理原始文档和 text units，query 会把问题和检索上下文交给配置的模型；改成外部 provider 就可能造成资料外泄。

12. 验证方法

Zhulong 的可信度来自可复跑验证，不是口头说明。

npm test
npm run verify:ci
npm run verify:release
npm run verify:local-rag

# 维护者内部审计 / 对标
npm run dev:audit:full

node scripts/run-full-test-plan.mjs --run-id round-1
node scripts/run-full-test-plan.mjs --run-id round-2

# 外部 GraphRAG 验证，只能在允许外发脱敏 fixture 时使用
GRAPHRAG_API_KEY=<your key> npm run verify:integration -- --live-graphrag

scripts/verification-manifest.mjs 是唯一任务目录：verify:ci 运行可重现 PR gate，verify:release 运行完整发布层，verify:local-rag 追加真实本地 RAG smoke。同一 verifier 在一个 tier 中最多运行一次，最终索引写入忽略的 verification/reports/verification-<tier>-index.*。

dev:audit:full 是维护者内部机制：它在 .zl-audit/latest/ 生成 scorecard、命令/skills/feature 分表、Zhulong / GSD / Superpowers 对标、时间拆分和 token 统计边界，并把可提交摘要写到 verification/reports/developer-audit-summary.md。Benchmark comparison 是所有对标行的保守平均，不是 Zhulong 单体分；本轮 Zhulong 产品平均为 90 / A，scorecard 里的 87 反映了 graph-lite 低成本路径、full-local 无文档正确阻断、GSD / Superpowers replay 可信度上限。默认 benchmark 是 deterministic，不调用外部 AI，所以 token 写 TOKEN_USAGE_UNAVAILABLE；GSD / Superpowers 使用本机真实 skill/plugin 文件做 skill-pack-backed-replay，记录 instruction pack hash、fixture、代码改修、测试和证据文件。真实 Codex 子进程必须显式设置 ZHULONG_AUDIT_REAL_AI=1，并使用 --ephemeral --ignore-rules --json；需要完全不读用户配置时再加 ZHULONG_AUDIT_CODEX_IGNORE_USER_CONFIG=1。本轮真实子进程已经尝试执行，但当前账号不支持默认 gpt-5.3-codex 模型，三个 subprocess 均在启动阶段失败，因此没有 usage events，token 没有数字化。

13. 项目生命周期教程

Zhulong 在新项目和既存项目中的使用顺序不同。关键原则是：新项目先建立工作台，既存项目先建立代码基线；文档更新后必须重扫文档，代码结构更新后必须重扫 codebase/graph。

zl-init --target "$PWD" --template greenfield-app --name order_app --mode new --doc-policy reference --rag none
zl-codebase-scan --target "$PWD"
zl-docs-sync --target "$PWD"
zl-new-milestone --target "$PWD" "MVP1 注文管理"

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

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

zl-preflight --target "$PWD"
zl-refresh-plan --target "$PWD"
zl-docs-sync --target "$PWD"

# 需要重建本地 GraphRAG index 时再执行
zl-docs-sync --target "$PWD" --index

zl-codebase-scan --target "$PWD"
zl-preflight --target "$PWD"
zl-refresh-plan --target "$PWD"
zl-refresh-run --target "$PWD" --graph
zl-graph-status --target "$PWD"
zl-graph-impact --target "$PWD" --files "src/a.js"
zl-graph-risk --target "$PWD"

zl workflow run debug --target "$PWD" \
  "请调查并修复退款上限与业务规则不一致" \
  --source user-message --intent fix
zl-workflow-audit --target "$PWD"
zl-workflow-continue --target "$PWD" --gate plan \
  --evidence .planning/workflows/<workflow-id>/PLAN.md
zl-workflow-continue --target "$PWD" --gate implementation \
  --evidence .planning/workflows/<workflow-id>/IMPLEMENTATION.md
zl-workflow-continue --target "$PWD" --gate verification \
  --evidence .planning/workflows/<workflow-id>/VERIFICATION.md
zl-evidence-record --target "$PWD" "退款规则已验证" --command "npm test" --result "passed" --writeback .planning/issues/CR-017.md
zl-evidence-status --target "$PWD"
zl-gate-check --target "$PWD"
zl-completion-check --target "$PWD"  # read-only eligibility
zl workflow complete --target "$PWD" # explicit state transition

14. CLI 内部机制

Zhulong 的 runtime 适配不是为每个 AI 工具写一套业务逻辑，而是让它们统一落到本地 CLI。bin/zl.mjs 是稳定入口，参数和路由实现位于 src/cli/。

zl-debug
  -> workflow run debug

zl-codebase-scan
  -> codebase scan

zl-completion-check
  -> workflow completion-check

zl-cockpit-build
  -> cockpit build

Codex: ~/.codex/skills/.../SKILL.md
Claude Code: ~/.claude/skills/.../SKILL.md
Copilot: .github/prompts/*.prompt.md

15. 命令面总览

这里是技术教程里的快速索引。完整参数、示例和产物见命令手册；本表用于确认 Zhulong 的能力层和命令入口没有断层。

16. Artifact contract

以后扩展 Zhulong 时，先定义 artifact contract。没有本地文件落点的能力，很难被 guard 检查，也很难证明真的接入。

17. 排障方法

Zhulong 出问题时，按 gate 从前到后排查。不要先怀疑 AI runtime，先看本地 artifact 是否存在。

18. CLI 输出与环境诊断

Zhulong 的所有顶层命令共享同一机器输出信封。普通结果进入 stdout，诊断进入 stderr；开启 --json 后，只输出一个符合 schemas/cli-output.schema.json 的 JSON 对象。

zhulong doctor --target "$PWD"
zhulong doctor --target "$PWD" --json
zhulong mode status --target "$PWD" --quiet
zhulong completion bash
zhulong completion zsh
zhulong completion fish

19. 如何扩展

新增能力时，遵守这个顺序：先定义本地 artifact，再接 CLI 命令，再接 runtime pack，最后补 verification。

新增一个 Zhulong 命令的建议步骤

1. 在 README / docs/changelog.md / docs/commands.html / docs/quality-plan.md 定义用户入口和目标 artifact。
2. 在 src/cli/args.mjs 增加 alias，并在对应领域模块增加 handler。
3. 在 handler 中只写目标项目内的文件，不把数据散落到 Zhulong 仓库。
4. 如果是 workflow 或 cockpit 这类 AI runtime 可直接触发的命令，更新 runtime/codex、runtime/claude-code、runtime/github-copilot 的调用说明。
5. 增加专项 verification；命令面还要进入 verify:full-command-surface。
6. 跑 npm run check && npm test && npm run verify:ci；发布相关变更再跑 npm run verify:release。

新增一个外部工具适配器的建议步骤

1. 在 .planning/config.json 定义 command，例如 update_command 或 query_command。
2. 不带 --run 时先生成 handoff，让用户能审查会执行什么。
3. 带 --run 时执行命令，并把结果复制/摘要到 .planning/。
4. status/query/diff 命令只读取 .planning/，不要强依赖外部工具实时可用。
5. verification 中用 fixture provider 证明离线可测，再提供 live provider 开关。