Zhulong Project Intelligence Kit
适配文档密集型与非文档密集型项目的通用本地 AI 工程情报框架。
在线文档通过 GitHub Pages 发布。README 中的产品、命令和技术指南链接会打开渲染后的网页，而不是 GitHub 的 HTML 源码视图。文档站首页：Zhulong 在线文档。
产品介绍 · 品牌与特色 · 命令手册 · 技术指南 · 质量计划 · 稳定验证基线
Zhulong Kit 是为 AI 编程工作准备的通用本地项目情报层。它帮助 AI 助手读取项目状态、按需检索项目资料、分析代码影响面、执行工作流门禁，并在任务完成前写回验证证据。它不绑定国家、语言、行业或技术栈，新项目、既有代码库、文档密集型项目和非文档密集型项目都可以按自己的约束接入。
它不替代 Codex、Claude Code、GitHub Copilot、GraphRAG 或 Graphify。它负责把这些工具连接到同一套本地项目记忆、证据链和确定性检查上。
--rag none 是非文档密集型项目的正式运行模式，不是功能不完整的降级模式。它关闭 RAG 安装、索引和 RAG 查询，但保留 workflow、codebase、Graphify、policy、evidence 与 completion gate；项目仍可按需使用轻量文档扫描和直接引用。只有当文档本身是需求、验收或合规依据时，才需要切换到 --rag local。
zhulong
-> 读取项目状态
-> 按需查询需求、测试、决策记录与设计资料
-> 检查代码地图、影响面与新鲜度
-> 执行工作流门禁和质量验证
-> 写回证据、风险与后续任务
照亮项目状态，让每个结论有依据，让每次完成经得起检查。
Zhulong 的名字来自掌管昼夜与秩序的烛龙。这个意象在产品中对应三件具体的事：把隐藏的项目状态变得可见，把分散的代码、资料和决策关系组织成证据，把自动化限制在用户能够预期的边界内。
| 特色 | 解决的问题 | 机制与证据 |
|---|---|---|
| 烛照全局 | 不知道当前缺什么、下一步做什么 | zl-next 只给 2-3 条建议；cockpit 聚合真实制品 |
| 机械判定 | 规格暧昧、制品缺字段、回答无依据 | ambiguity、structure、answer 三组纯规则审计 |
| 证据闭环 | 结论和验证只留在聊天里 | citation、trace、evidence writeback 和完成门禁 |
| 昼夜有序 | 普通命令暗中联网或执行重刷新 | 只自动折叠零成本审计，重命令始终显式 |
| 本地边界 | 源码和规格可能误发到外部服务 | local-only、offline lock、privacy 与 outbound audit |
每项特色都按“用户问题、工作机制、关键产物、验证证据、能力边界”记录，完整规范见品牌与特色能力规范。
| 场景 | 名称 |
|---|---|
| 主品牌 | Zhulong（烛龙） |
| 完整名 | Zhulong Project Intelligence Kit |
| 短名 | Zhulong Kit |
| 主命令 | zhulong |
| 短命令 | zl |
| 直接命令 | zl-* |
| npm 包 | zhulong-kit |
| 本地工作台 | .planning/ |
- Node.js 24 LTS。
- npm 11 或更高版本。
- 默认零运行时依赖，GraphRAG 与 Graphify 按需接入。
仓库提供 .nvmrc 和 .node-version，用于统一本地 Node.js 版本。
| 平台 | 支持状态 | 验证范围 |
|---|---|---|
| Linux | 正式支持 | Ubuntu 完整质量 gate 与双项目画像 smoke |
| macOS | 正式支持 | Node.js 24、CLI、rag none、文档模式和 workflow smoke |
| Windows | 暂未正式支持 | 当前仍有 POSIX shell 与路径假设，完成兼容改造前不作支持承诺 |
在仓库内直接运行：
node bin/zl.mjs --help
node bin/zl.mjs docs status --target "$PWD"建立本地命令链接：
npm link
zhulong --help
zl docs status --target "$PWD"初始化一个已有项目：
zhulong init --target "$PWD" \
--template brownfield-monorepo \
--name my_project \
--mode existing \
--doc-policy reference \
--rag none
zhulong codebase scan --target "$PWD"
zhulong preflight --target "$PWD"
zhulong verify --target "$PWD"同一能力也可以使用短命令：
zl-init --target "$PWD" --template brownfield-monorepo --mode existing --doc-policy reference --rag none
zl-codebase-scan --target "$PWD"
zl-preflight --target "$PWD"
zl-completion-check --target "$PWD"Zhulong 默认采用 interactive 工作流语义：当前 Skill 只处理用户当前请求，输出“建议下一步”不等于获准执行下一步。调查、分析、诊断 默认只产出根因和证据；只有用户明确说“修复”“实现”“继续执行”或当前任务附带匹配的有界 Goal 授权时，才可以修改代码或跨 workflow 推进。
用户可以直接用自然语言授权一组明确的 MVP，例如“自动执行 MVP4.0 到 MVP4.7，完成后停止”。Runtime 会把每个 MVP 的描述编译为保存在 .planning/goals/ 的结构化合同；child workflow 必须使用合同中的精确 objective，并携带授权 ID、milestone 与 contract digest。执行、修复、完成和推进不接受只有 milestone 名称的旧式 grant；依赖、commit、push、merge、release 还要通过权限检查。
Workflow alias 不会自动把调用者标记为用户。只有直接响应当前用户消息的 runtime 才能附加 --source user-message；这是跨 runtime 的可审计语言合同，不是密码学身份认证。代理自行选择的下游 Skill 不得附加该标记。
当前用户消息只授权它明确要求的工作，不会提前接受尚未生成的结果。zl-completion-check 现在只判断当前 workflow 是否具备完成资格，不改变状态。只有显式的 zl workflow complete，并且当前 workflow 的类型化产物、证据、writeback 和后续用户验收或 Goal 授权全部通过时，才会写入 complete。若原始消息明确同时要求“完成/关闭”，runtime 才可记录预先的完成意图。完整语义见工作流授权合同。
所有顶层命令都接受统一输出参数：
zhulong doctor --target "$PWD"
zhulong doctor --target "$PWD" --json
zhulong mode status --target "$PWD" --quiet
zhulong completion bash
zhulong completion zsh
zhulong completion fish--json只向 stdout 写一个符合schemas/cli-output.schema.json的 JSON 对象，并把命令诊断收进stderr数组。--quiet抑制正常 stdout，但不吞掉 stderr 错误。--no-color移除 ANSI 控制序列，适合 CI 和日志解析。- 退出码固定为：
0成功、1命令或 gate 失败、2用法错误、3必需环境缺失、70内部错误。 doctor检查 Node.js、npm、Git、浏览器能力和项目 RAG 模式；本地 RAG 工具仍是按需项。
完整决策见 CLI 输出与退出码 ADR。
| 能力 | 作用 | 常用入口 |
|---|---|---|
| 项目接入 | 建立项目清单、规划目录和运行基线 | zhulong init |
| 代码地图 | 扫描技术栈、目录、测试和架构 | zhulong codebase scan |
| 文档智能 | 抽取、规范化、同步并查询本地文档 | zhulong docs sync |
| 本地检索 | 显式初始化本地 RAG，不在日常命令中执行隐藏重建 | zhulong rag init-local |
| 影响分析 | 构建代码图并分析变更影响和风险 | zhulong graph build |
| 里程碑工作流 | 从需求、计划、实现到验证组织完整闭环 | zhulong workflow run new-milestone |
| 条件化前端设计 | 通过 $zl-ui-phase 在继承现有设计与 Taste 视觉增强之间路由 |
zl-ui-phase |
| 缺陷调查 | 结合规格证据和代码地图定位问题 | zhulong workflow run debug |
| 回答审计 | 检查引用、数值漂移和答案接地情况 | zhulong answer audit |
| 暧昧审计 | 检查多语言需求与验收条件中的不可验证表达 | zhulong ambiguity audit |
| 结构审计 | 校验关键 .planning/ 制品的 mini-schema |
zhulong structure audit |
| 下一步发现 | 根据项目状态推荐 2-3 条命令 | zhulong next |
| 完成门禁 | 只读检查完成资格；显式 complete 才改变状态 | zhulong workflow completion-check |
| 项目驾驶舱 | 生成本地静态项目状态与证据页面 | zhulong cockpit build |
| 场景 | 推荐设置 | 默认不会做的事 |
|---|---|---|
| 非文档密集型项目 | --doc-policy reference --rag none |
不安装、索引或查询 RAG；workflow、代码地图和 evidence 正常工作 |
| 文档密集型项目 | --doc-policy strict --rag local |
不使用未经批准的外部服务；把引用、新鲜度和回答依据纳入门禁 |
| 已有代码库 | 先扫描代码，再同步文档，按需构建代码图 | 不移动业务源码到 .planning/ |
| 文档或决策记录更新 | 先执行轻量同步，确有需要时再显式建索引 | 不自动执行重型 GraphRAG 刷新 |
| 发布或交接 | 执行完成检查、策略检查和质量收口 | 不把缺失证据视为已完成 |
多语言能力只是审计覆盖，不是使用前提。内置中、英、日词表用于验证不同语言的需求表达；Zhulong 的项目模型、工作流和门禁对地域与语言保持中立。
Zhulong 内置经过约束的 Taste Adapter，用于减少新前端的模板化 AI 味，但 Taste 不是所有 UI 的默认美术风格。$zl-ui-phase 会从 manifest、请求、依赖与有界项目路径证据实际计算 Frontend Design Decision；runtime 再用品牌资料和现有页面补充判断，低置信度时只询问一个方向问题：
| 模式 | 场景 | Taste 权限 |
|---|---|---|
create |
全新 landing page、官网、portfolio | 完整应用与项目匹配的 Taste 规则 |
evolve |
风格已出现但仍零散的自然演进项目 | 保留品牌基础，增强层级、节奏、版式和交互 |
preserve |
已有成熟设计系统、视觉稿或品牌规范 | 只审计，不擅自替换字体、颜色、圆角和组件库 |
system |
Dashboard、后台、数据表和多步骤产品 UI | 关闭营销页面 Taste，服从产品设计系统 |
项目可在 project.manifest.yml 使用 frontend_design.strategy 和 frontend_design.taste 覆盖自动判断。Taste 已随 Zhulong 分发，不需要另行安装上游 skill；用户明确要求和项目设计证据始终优先。
- Zhulong 默认执行
local-only网络策略。 - Codex、Claude Code、GitHub Copilot 是外部 runtime，只由用户主动调用，不改变 Zhulong 命令的本地边界。
.planning/保存生成的项目情报制品。reference模式把缺失证据记录为风险，不阻断普通开发。strict模式会把缺失引用、过期代码图、过期 RAG 和策略失败纳入硬门禁。- 外部 RAG 必须通过
--allow-external-rag显式启用。 - 索引重建、代码图重建和外发操作必须由用户明确触发。
- 项目驾驶舱是本地静态 HTML，不需要远程服务。
| 命令 | 作用 |
|---|---|
zl-preflight |
只检查当前状态，不执行重型刷新 |
zl-refresh-plan |
根据文档和代码变更生成刷新建议 |
zl-refresh-run |
在用户明确指定后执行 RAG 或代码图刷新 |
zl-mode-status |
查看当前文档、RAG、代码图和严格模式状态 |
zl-mode-set |
切换 graph-lite、full-strict 等运行模式 |
| 运行环境 | 目录 | 命令前缀 |
|---|---|---|
| Codex | runtime/codex/skills/zl-* |
$zl-* |
| Claude Code | runtime/claude-code/skills/zl-* |
/zl-* |
| GitHub Copilot | runtime/github-copilot/prompts/zl-*.prompt.md |
/zl-* |
| 文档 | 内容 |
|---|---|
| 产品介绍 | 产品定位、能力和常见疑问 |
| 品牌与特色能力规范 | 品牌基础、定位、特色支柱、语言与视觉规范 |
| 命令手册 | 全部命令、参数、输出和失败示例 |
| 技术指南 | 架构、工作流、RAG、Graphify 和运行环境说明 |
| Cockpit 样例 | 本地项目驾驶舱的静态样例 |
| 质量计划 | 测试矩阵、质量门禁和证据标准 |
| CI 与发布治理 | GitHub Actions、ruleset、trusted publishing 与制品元数据 |
| 开源发布五轮复核 | Apache 2.0、Pages、治理、安全与发布证据 |
| 运行环境包说明 | Codex、Claude Code 和 GitHub Copilot 安装方式 |
| 提取与本地计划 | 截图提取、工程基线和后续优化路线 |
| 稳定验证基线 | 经确认、适合长期引用的质量与分发基线 |
| 工程收口计划 | v0.1.0 发布门槛与 v0.2.0 架构演进路线 |
| 架构决策记录 | 模块边界、CLI 契约和平台支持决策 |
基础检查：
npm run check
npm run verify:docs
npm run verify:naming
npm run verify:runtime
npm run verify:skills-usability
npm run verify:ambiguity
npm run verify:structure
npm run verify:guardrails
npm run verify:visual
npm run verify:design
npm run verify:pages
npm run verify:public-release
npm run verify:cli-contract发布级检查：
npm run verify:ci
npm run verify:release
npm run verify:business-chainverify:ci 只包含 GitHub Actions 可重现的确定性检查，verify:release 是发布前完整层；两者都由同一验证 manifest 调度，同一轮中每个 verifier 最多执行一次。需要 Ollama 和本地 GraphRAG 的真实集成验证使用 npm run verify:local-rag。
verify:visual 使用 Playwright 和 axe 检查文档与 cockpit 的桌面、移动端、暗色主题、布局及 WCAG A/AA serious/critical 问题。verify:design 固化品牌素材、信息层级、动效边界和反模板化规则，防止后续修改退回通用 AI 产品页样式。
npm 包通过 files 白名单只包含 CLI、模板、运行环境包、schema、adapter 和主图标。验证截图、图标候选集、历史报告与本地审计目录不会进入发布包。
主图标统一使用 docs/assets/zhulong-icon.png。
本项目使用 Apache License 2.0。该许可证包含明确的版权授权、专利授权、再分发条件和免责声明。外部工具与非内嵌材料的许可边界见 THIRD_PARTY_LICENSES.md。
npm 后续版本使用 GitHub OIDC trusted publishing，不保存长期发布 token。由于 npm 只允许给已经存在的包配置 trusted publisher，zhulong-kit@0.1.0 首发必须先由仓库所有者提供一个一次性 granular token；GitHub-hosted release workflow 会生成 provenance，发布成功后必须立即配置 Trusted Publisher、删除 GitHub secret 并撤销该 token。
- 贡献流程：CONTRIBUTING.md
- 社区行为规范：CODE_OF_CONDUCT.md
- 安全漏洞私密报告：SECURITY.md
- 使用支持：SUPPORT.md