Lumina - everything-claude-code：AI开发工具包

0. 定位

Everything Claude Code 不是业务应用，而是一套把 AI 编程习惯打包成可安装插件的工作流配置：agents、commands、skills、rules、hooks、MCP 配置和少量 Node.js 脚本。它的价值不在“实现了一个复杂运行时”，而在于把个人经验拆成可组合、可触发、可验证、可迁移的工作流单元。

这份 WorldFlowAI 仓库是一个定制 fork：插件 manifest 仍指向原作者的 affaan-m 仓库，而 WORLDFLOWAI.md 增加了 Synapse/Arbiter 的项目使用说明。快照中有 9 个 agents、15 个 commands、14 个 skill 文件、8 个 rules、8 个脚本文件和 4 个测试文件；运行 node tests/run-all.js 得到 62/62 通过。这里的测试主要验证工具脚本和配置自身，并不等价于“AI 生成代码质量已经被证明”。

1. 总体架构

用户任务
   │
   ├── commands/       把常见意图变成显式入口：/plan /tdd /verify /learn
   │       │
   │       ├── agents/  把角色、工具权限、模型和输出责任写成可复用角色
   │       └── skills/  把领域知识、流程和评价标准写成可组合知识模块
   │
   ├── rules/           全局约束：安全、测试、Git、性能、委派
   ├── hooks/           工具事件上的自动提醒、阻断、格式化、状态持久化
   ├── contexts/        按开发/评审/研究阶段注入动态上下文
   └── mcp-configs/     可选的外部工具连接配置

scripts/lib + scripts/hooks
   └── 提供跨平台路径、文件、日期、包管理器检测和会话生命周期脚本

层	目录	作用	学习重点
入口层	`commands/`	将模糊的“我要开发/修 bug/评审”变成固定指令	工作流应该有稳定入口，而不是只靠提示词临场发挥
角色层	`agents/`	限定角色职责、工具权限、模型选择和输出格式	角色边界比“一个万能 Agent”更容易控制质量
知识层	`skills/`	保存 TDD、评估、压缩、后端/前端模式等长文本知识	把项目经验从对话上下文变成可复用资产
约束层	`rules/`	持续生效的团队规范	将不可妥协的安全/测试要求前置
事件层	`hooks/` + `scripts/hooks/`	在 SessionStart、PreToolUse、PostToolUse、PreCompact、Stop 等事件触发	让质量控制靠事件自动发生，而不是依赖记忆
适配层	`scripts/lib/`	跨平台路径和包管理器选择	把环境差异收敛在一个小适配层
外部能力	`mcp-configs/`	GitHub、Supabase、Vercel、Cloudflare 等 MCP 配置	外部工具按项目启用，避免全部工具常驻上下文

2. 核心流程

2.1 “命令 → 角色 → 交接”的工作流编排

/orchestrate 用 Markdown 定义了 feature、bugfix、refactor、security 四类流程。例如 feature 流程是：

planner → tdd-guide → code-reviewer → security-reviewer

每一站都要求输出结构化 handoff：已完成工作、发现、修改文件、开放问题、建议。这个设计的关键不是 agent 数量，而是把上下文交接协议写清楚，让下一站不必重新猜测上一站做了什么。对应文件是 commands/orchestrate.md 的“Execution Pattern”和“Handoff Document Format”。

不过需要准确理解：这个仓库里的 /orchestrate 主要是工作流契约和提示模板，并没有看到真正负责启动多个子进程、传输 handoff、聚合结果的编排运行时代码。它更接近“可执行的操作手册”，不是完整的 orchestration engine。

2.2 会话生命周期与上下文持久化

当前实现形成了一个轻量生命周期：

SessionStart 创建 ~/.claude/sessions 和 learned skills 目录，扫描最近 7 天的 session 文件，并检测包管理器。
PreCompact 在上下文压缩前写入 compaction 日志，并在当天的 .tmp session 文件中记录压缩事件。
SessionEnd 创建或更新时间戳 session 文件。
Stop 阶段的 evaluate-session.js 统计 transcript 中的 user 消息数；达到默认 10 条后，提示 Claude 评估可复用模式。

它体现了一个非常值得借鉴的思路：把“上下文窗口会丢信息”当成系统约束来设计，而不是把它当成模型偶发缺陷。压缩前保存阶段性状态，下一次启动时提供最近状态入口，形成了最小可用的跨会话连续性。

但实现仍是半自动的：evaluate-session.js 只发出“请评估并保存”的提示，没有从 transcript 自动抽取模式或写入 learned skill；session-start.js 也主要报告路径和数量，没有自动把 session 内容注入当前上下文。因此，README/skill 中的“自动提取和加载”比当前脚本实际做到的更多。

2.3 工具事件上的质量闸门

hooks/hooks.json 将质量控制分布到工具生命周期：

PreToolUse：阻止脱离 tmux 的开发服务器；对长命令给出 tmux 提醒；阻止随意创建 .md/.txt；编辑/写文件时提示压缩。
PostToolUse：编辑 JS/TS 后运行 Prettier；编辑 TS/TSX 后尝试运行 tsc --noEmit；发现 console.log 时警告；创建 PR 后打印 review 命令。
Stop：检查本次修改文件里的 console.log。

这里最值得学习的是“把规则放在事件边界上”：例如代码格式化应该在编辑完成后立刻发生，文档文件约束应该在创建动作前阻止，而不是等到 PR 阶段才提醒。另一个好点子是区分阻断和提醒：真正违反流程的动作可以 block，低风险问题只 warning，避免自动化变成摩擦源。

3. 技术设计亮点

3.1 把个人经验拆成四种不同粒度

它没有把所有经验都塞进一份巨大 CLAUDE.md，而是区分：

command：用户主动触发的一次工作流；
agent：具有角色和权限边界的执行者；
skill：可复用知识和方法；
rule：默认持续有效的硬约束。

这相当于给“提示词资产”做了模块化设计。迁移到自己的 Tauri/Node/Rust 项目时，可以把项目规则、调试技能、一次性流程和审查角色分别维护，降低上下文噪声和修改风险。

3.2 用最小权限表达角色差异

例如 planner 只有 Read, Grep, Glob，主要负责理解和规划；code-reviewer 增加了 Bash，可以检查 diff 和运行验证；security-reviewer 拥有 Write, Edit, Bash，因为它被设计成既发现问题又推动修复。

这不是完整的安全沙箱，但它至少把“角色应该能做什么”显式化了。对于多 Agent 系统，工具权限表往往比角色名称更能决定风险边界。

3.3 把验证从“最后检查”升级成开发闭环

仓库同时提供 TDD、verification loop 和 eval harness：

需求前：定义 capability / regression eval
开发中：RED → GREEN → REFACTOR
阶段性：build → type → lint → test → security → diff
提交前：checkpoint 对比基线

尤其值得学习的是把 AI 任务的成功标准提前写出来，并区分 capability eval（新能力是否出现）与 regression eval（旧行为是否保持）。对于 AI 生成代码，单次“看起来能用”不够，需要记录 pass@k（k 次尝试至少成功一次）或 pass^k（连续 k 次都成功）这类可靠性指标。

3.4 用模型分层控制成本和质量

rules/performance.md 建议轻量任务使用低成本模型，主开发和编排使用中高能力模型，架构决策和研究使用最强模型；同时提醒不要把上下文窗口最后 20% 用在大型重构或复杂调试上。

可迁移的不是其中的具体模型名称，而是“任务复杂度 → 模型能力 → 上下文预算”的映射。模型选择应该像数据库连接池或编译资源一样成为工作流策略，而不是每次随意决定。

3.5 包管理器检测体现了环境适配的优先级设计

scripts/lib/package-manager.js 采用明确的优先级：环境变量 → 项目配置 → package.json → lock 文件 → 全局配置 → 当前可用工具 → npm 默认值。每个检测结果同时返回 name/config/source，因此不仅知道“选了什么”，还知道“为什么选它”。

这个返回 source 的小设计很实用：出现环境问题时，诊断信息能直接告诉你是被环境变量、项目配置还是 lock 文件影响的，避免黑盒自动检测。

3.6 跨平台迁移集中在共享工具层

脚本用 Node.js 的 path.join、os.homedir()、os.tmpdir() 和文件 API 处理路径、目录、日期和读写，把 Windows/macOS/Linux 差异集中在 scripts/lib/utils.js。这是比“每个 hook 各自写一套 shell”更容易维护的方向。

但仓库仍保留旧的 .sh hook 和 skill 示例，说明迁移还没有完全收口；学习时应借鉴“集中适配”的方向，不要直接复制当前所有实现。

3.7 插件 manifest 让配置集合具备分发能力

.claude-plugin/plugin.json 只声明元数据、commands 和 skills 路径，再通过 marketplace 安装。这样，工作流资产可以像依赖包一样版本化、安装、升级和贡献，而不是散落在每个人的 home 目录里。

对于团队内部工具，可以进一步加上版本兼容矩阵、变更日志、安装后的 smoke test 和回滚策略。

3.8 对自己的工具也写测试

项目没有业务代码，却仍为 utils.js、包管理器检测、hook 脚本和 hooks.json 写了 62 个测试。这传达了一个容易被忽略的原则：自动化基础设施本身也是生产代码，坏一个 hook 就可能阻断所有开发任务。

4. 不要直接照搬的地方

“连续学习”目前不是完全自动学习。 文档写的是自动提取、保存和加载，但实现主要是计数、提示和写 session 模板。若用于生产，应补上 transcript 解析、候选模式生成、人工确认、冲突合并和回滚。
workflow 文档不等于编排引擎。 /orchestrate 描述了理想的 agent 链，但没有看到真正的调度、超时、重试、状态机、结构化输出校验和失败恢复。要构建可靠 harness，需要把 handoff 做成 schema，并让每一步有可恢复状态。
80% coverage 是规范，不是仓库实证。 当前仓库没有 package.json、没有看到 CI 配置，内置测试 runner 只汇总自定义测试输出，也没有生成覆盖率报告。不要把“要求 80%”误读成“已经达到 80%”。
hooks 有较高执行权限和副作用。 其中会调用 npx、prettier、tsc、shell/Node 命令，并读写用户目录；MCP 配置也可能连接 GitHub、数据库和部署平台。安装前必须逐条审计命令、路径、网络访问和 token 来源。
状态文件模型很简陋。 当天多个会话共享一个 session 文件，扫描最近文件和更新内容没有锁，也没有清晰的会话 ID 数据模型；多人、多进程或并行 Agent 场景下可能互相覆盖。
规则有模板化倾向。 OWASP、TDD、架构模式等内容很全面，但部分是通用清单，未必适合每个项目。应从高频真实问题中筛选规则，避免规则数量过多导致模型注意力稀释。

5. 设计哲学总结

这个项目最值得学习的不是某一条提示词，而是以下组合：

把 AI 编程视为“工作流系统”，而不只是聊天。
把经验拆成 command、agent、skill、rule 四种可治理资产。
用事件 hook 把一部分质量控制前移到动作边界。
用 session、checkpoint、compact 处理上下文的有限性。
用 TDD、verification、eval 把“感觉完成了”变成可检查的证据。
用模型分层、工具权限和 MCP 开关控制成本与风险。
对配置、脚本和 hook 自身测试，而不是只测试业务代码。

如果只挑三个实践迁移到自己的项目，我建议按这个顺序：

先建立 /plan → /implement → /verify → /review 的最小闭环，并把每步输出格式固定下来。
再把项目规则拆为“默认规则”和“按需技能”，减少一份巨型上下文文件。
最后挑 2–3 个低风险 hook 做自动化，例如编辑后格式化、提交前 diff 检查、长会话 checkpoint 提醒。

everything-claude-code：AI开发工具包

内容