Zhulong Project Intelligence Kit - 通用 AI 项目智能框架

五个能被验证的特色，不是一组宣传口号。

每项能力都对应真实摩擦、本地制品和独立验证脚本；完整记录规则见品牌与特色能力规范。

烛照全局

问一句“下一步做什么”

zl-next 读取当前项目状态，只给 2-3 条命令；cockpit 用真实制品呈现状态，不用总分掩盖缺口。

机械判定

质量不交给模型猜

暧昧、结构和回答审计只使用正则、集合、mini-schema、数值比较和词法重叠。

证据闭环

结论能够回到来源

引用解析率、数值漂移、追踪矩阵和 evidence writeback 共同证明“为什么这样改”。

昼夜有序

自动化没有惊吓

默认只执行当前 Skill；多个 MVP 可用一次有界 Goal 授权自动推进。索引、代码图和越界动作始终要求显式许可。

本地边界

项目资料默认留在本机

local-only、offline lock、外发审计和中性权限模板共同界定网络与敏感文件访问。

本地工程控制面，而不是另一个聊天入口。

三个 runtime 入口都落到同一套 zl-* 命令和 .planning/ 本地制品，页面视觉也统一成控制台式信息模块。

control plane

Codex Claude Code GitHub Copilot Zhulong CLI .planning/ Completion Gates

knowledge

需求 / 决策 / 运行资料

需要文档智能时，来源、RAG 查询和引用结果统一落到 .planning/knowledge/；rag none 项目无需建立索引。

impact

Graphify 网络

代码影响面以节点和关系表达，不再用装饰线假装图谱。

proof

Evidence writeback

测试、验证、风险和结论写回当前 workflow；completion check 只判断资格，显式 complete 才改变状态。

policy

MVP6 policy contract

zl-policy-lock、zl-policy-verify、zl-policy-diff 把 local-only、profile 和四态 gate 固化为本地合同。

freshness

MVP3.5 refresh control

zl-preflight 和 zl-refresh-plan 只提醒；zl-refresh-run 才显式刷新 GraphRAG / Graphify。

不是更会写代码，而是更知道为什么改。

普通 AI coding 只看到 prompt 和当前文件。Zhulong 让 AI 先读项目状态、代码影响面和验证要求，再根据项目模式决定是否接入需求、决策记录和其他文档证据。

维度

普通 AI Coding

Zhulong Project Intelligence Kit

输入

一段 prompt、当前打开文件、聊天上下文。

项目状态、代码地图、测试策略、历史 evidence，以及按需启用的文档知识层。

改修前

靠模型猜测影响面，容易漏掉旧系统边界。

先跑 zl-codebase-scan 和 Graphify，把入口、依赖、风险模块显式化。

文档依据

需要人工复制粘贴，文档一多就断层。

zl-docs-sync、zl-docs-query、zl-answer-audit、可选 GraphRAG，把依据和审计写回 .planning/。

完成定义

“改完了”往往停留在对话里。

completion gate 还检查 privacy、interaction policy、当前工作授权、结果验收或 Goal、结构化决策，以及绑定当前 workflow 的 plan、implementation、verification、evidence 和 writeback。

四个层次，组成一个工程控制面。

Zhulong 的价值不是把几个工具绑在一起，而是把它们变成 AI 开发时必须经过的上下文路径。

Workflow guard

Zhulong native workflow 默认只执行当前阶段；自然语言多 MVP 请求会生成本地、可撤销的有界 Goal。前端任务再由 zl-ui-phase 在 preserve、evolve、create、system 间路由。

Document intelligence

按需把需求、ADR、QA、会议记录、设计与运行手册变成可扫描、可查询、可引用的本地知识层；非文档密集型项目可关闭 RAG。

Code map

Graphify 提供代码地图和影响面。Zhulong 负责把图谱产物同步进 .planning/graphs/，供 workflow 使用。

Evidence loop

测试命令、验证结果、风险判断和可选来源引用都绑定当前 workflow。zl-completion-check 只判断能不能收口，zl workflow complete 才显式关闭。

面向各种项目现场的真实摩擦。

Zhulong 处理的是项目状态不透明、代码影响面不清、完成条件不可靠，以及文档存在时依据难追踪的问题，不绑定国家、语言或行业。

需求变更

先把变更点进入 zl-spec-phase，记录未决点；存在正式依据时再查询和引用文档，然后生成计划。

缺陷调查

zl-debug 会写 context packet，把问题证据、Graphify 影响面和验证 gate 串起来。

既存改修

既有项目初始化后必须跑 zl-codebase-scan。没有 codebase baseline，guard 不允许轻易完成。

前端设计

zl-ui-phase 先从 manifest、请求、依赖和有界项目路径实际计算设计模式，再由 runtime 用品牌、token、组件和页面证据复核。新营销页面可由 Taste 增强；成熟设计系统保持原样；Dashboard 使用产品设计系统。

文档更新

文档新增或变更后先跑 zl-docs-sync。它只标记 STALE_NEEDS_REFRESH，不自动重建 GraphRAG；需要新索引时再显式加 --index。

代码更新

别人提交和你当前任务无关时可以跳过重刷新；相关源码或测试变更才推荐 zl-refresh-run --graph。

开发者每天真正会用到的入口

zl-debug --target "$PWD" "支付状态更新异常"
zl-preflight --target "$PWD"
zl-refresh-plan --target "$PWD"
zl-docs-sync --target "$PWD"
zl-docs-query --target "$PWD" "退款规则依据"
zl-answer-audit --target "$PWD"
zl-graph-query --target "$PWD" "PaymentService"
zl-plan-phase --target "$PWD" "MVP1"
zl-execute-phase --target "$PWD" "实现状态修复"
zl-verify-work --target "$PWD" "验证支付流程"
zl-completion-check --target "$PWD"

Codex、Claude Code、Copilot 只是不同入口。真正稳定的能力边界是本地 zl-* 命令和 .planning/ artifact。

Zhulong 的工作方式

它不搬动你的项目，也不替代 IDE。它在目标项目根目录叠加一个本地工程控制面。

1. zl-debug / zl-plan-phase
启动 Zhulong workflow guard。

2. .planning/context
生成 context packet 和 handoff。

3. docs + graph
查询文档依据和代码影响面。

4. evidence
把验证记录写入 .planning/evidence/ 并回写 issue。

5. completion-check + complete
先只读检查资格，再显式改变状态。

本地 intelligence layer

target-project/
  src/
  docs/
  AGENTS.md
  project.manifest.yml
  .planning/
    codebase/
    knowledge/
    graphs/
    refresh/
    workflows/
    evidence/

Zhulong 的产物默认留在目标项目本地。外部流通只会来自你配置的 runtime、RAG provider 或 Graphify command。

每一步都有落点，不只停在聊天里。

Zhulong 会把 AI 开发过程拆成可检查的本地文件。你可以打开这些文件，确认它到底有没有接入文档、Graphify 和 workflow。

.planning/codebase/代码清单、结构、技术栈、测试策略、既有项目 baseline。

.planning/knowledge/文档来源、归一化结果、RAG handoff、RAG query result。

.planning/graphs/Graphify graph、报告、diff、staleness 检查。

.planning/workflows/workflow state、类型化 gate artifact、当前确认与决策状态。

.planning/goals/多 milestone 的 exact objective、contract digest、权限、停止条件与撤销状态；旧式 milestone-only grant 不允许修改型 action。

.planning/evidence/验证证据、命令输出摘要、source 引用、evidence index。

.planning/quality/RAG golden、citation audit、RAG eval，用来证明文档问答结果可信。

.planning/trace/文档、代码、测试、evidence 的追踪矩阵。

.planning/policies/完成前 policy check，保密和证据质量统一给出 PASS/FAIL。

.planning/refresh/记录 GraphRAG / Graphify 上次刷新 commit、preflight、refresh plan 和显式刷新结果。

AGENTS.md把 Zhulong 调用规则写进目标项目，让 runtime 更容易遵守流程。

成本可控，不把每个任务都变成全量重建。

MVP3.5 增加执行预算层。Zhulong 会告诉你 GraphRAG / Graphify 距离最新 commit 落后多少，以及这些 commit 是否真的改到了相关文档或代码。

轻量提醒

zl-preflight --target "$PWD"
sed -n '1,120p' .planning/refresh/PREFLIGHT.md

只读 git diff 和刷新账本，输出 heavy refresh executed: no。

差分计划

zl-refresh-plan --target "$PWD"
sed -n '1,160p' .planning/refresh/REFRESH_PLAN.md

无关 commit 显示 behind-unrelated；相关文档/源码才推荐刷新。

显式刷新

zl-refresh-run --target "$PWD" --rag
zl-refresh-run --target "$PWD" --graph
zl-mode-set --target "$PWD" docs-strict

真正刷新必须由命令触发，结果写回 REFRESH_STATE.json。

两条正式路线，按项目真实约束选择。

Zhulong 同等支持文档密集型与非文档密集型项目。rag none 专门服务非文档密集型路线；只有文档承担需求、验收或合规责任时，才启用本地 GraphRAG 和 citation gate。

非文档密集型路线

zl-init --target "$PWD" --doc-policy reference --rag none
zl-codebase-scan --target "$PWD"
zl-preflight --target "$PWD"

rag none 不安装、不索引也不查询 RAG，workflow、codebase、Graphify、policy、evidence 和 completion gate 仍完整工作。少量文档仍可轻量扫描和直接引用。

文档密集型路线

zl-init --target "$PWD" --doc-policy strict --rag local --setup-rag skip
zl-rag-init-local --target "$PWD"
zl-docs-index --target "$PWD" --run

适合以 PRD、合同、规范、ADR、运行手册或合规资料作为交付依据的项目。missing citation、RAG stale、外部 provider 会进入阻断逻辑。

演示路线

zl-cockpit-build --target "$PWD"

生成本地项目驾驶舱，展示 workflow、Graphify、RAG、policy、quality 和 evidence 状态；它只读已有 artifact，不执行重刷新。

适合的项目

Zhulong 是通用项目智能框架，从无文档原型到规范密集型交付都可接入；差别只是启用哪些上下文层和门禁。

新项目与轻量项目

使用 rag none，先建立 workflow、代码基线和 evidence，不为不存在的文档制造负担。

既有系统维护

先建立 codebase baseline，再用 Graphify 看影响面，避免凭感觉改旧系统。

文档与合规密集交付

启用本地 RAG、citation、trace、evidence 和 writeback，记录每次判断、验证、风险和后续事项。

可信度来自可复跑验证。

Zhulong 不要求你相信文案。它要求每个接入点都有命令、有产物、有验证报告。

接入验证

zl-verify --target "$PWD" 检查目标项目是否真的有 AGENTS.md、project.manifest.yml、.planning/。

能力验证

npm run verify:integration 覆盖 init、docs、Graphify、runtime pack、workflow guard 和 evidence；npm run verify:init-policy 覆盖 reference/strict 文档策略、none/local/external RAG 后端和外部 RAG opt-in；npm run verify:knowledge-reliability 覆盖 docs sync、docs query、answer audit；npm run verify:mvp3 覆盖 golden、citation、trace、policy、help skills；npm run verify:mvp35 覆盖 refresh/preflight/mode 控制；npm run verify:workflow-facade 和 npm run verify:policy-hardening 覆盖无感编排层和策略合同。

命令面验证

npm run verify:full-command-surface 会逐个执行 package.json 中全部 zl-* / zl bin 命令，避免“文档写了但实际不能用”。

项目驾驶舱

zl-cockpit-build 会把 Graphify 影响图、GraphRAG/RAG 证据链、workflow、quality 和 privacy 状态生成成本地静态 HTML，适合 leader 演示。稳定样例页在 templates/cockpit/sample.html，真实项目快照在 .planning/cockpit/index.html。

开发者审计 / 对标

npm run dev:audit:full 会生成维护者专用评分卡：74 个命令、33 个运行环境 skill/prompt、功能门禁、对标结果、耗时和 token 边界。历史评分只作为当次验证证据，不作为永久宣传数字；摘要位于 verification/reports/developer-audit-summary.md。

完成验证

zl-completion-check 会在授权、重大决策、类型化 artifact、evidence 或 writeback 缺失时阻断，而且不会自行把 workflow 标记为完成。

从第一条命令开始

新项目和既存项目都可以接入。区别是既存项目必须先扫描现有代码库，给 guard 建立 codebase baseline。

新项目

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

既存项目

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