项目定位

ForgeKit（仓库 CodeWithJuber/forgekit）是一套面向开发者的工具集，当前发布版本为 v0.27.3。它通过脚本化的安装与初始化流程，把"克隆即可用"作为主要目标，方便新用户快速搭建本地开发环境。资料来源：README.md:1-30 最新版本变更显示文档站点已切换为英文优先，并记录了自动本地化路径，说明项目把"文档自动化"作为长期演进方向之一。资料来源：README.md:CHANGELOG 段

安装与环境准备

package.json 定义了项目元数据、依赖与 npm 脚本入口，是了解可执行命令的起点。资料来源：package.json:1-40 在动手前，请确认本地已具备基础工具（Git、Node.js 与 shell 环境），随后按下列顺序进行安装：

1. 克隆仓库到本地工作目录。
2. 执行安装脚本 ./install.sh，脚本会自动解析依赖、写入默认配置并准备运行时。资料来源：install.sh:1-60
3. 如需初始化 Claude 相关工程脚手架，运行 ./bin/claude-init.sh，该脚本负责生成 Claude 相关的本地配置与项目骨架。资料来源：bin/claude-init.sh:1-80

升级到 v0.27.3 后，文档站点结构发生调整，官方文档以英文为准，自动本地化路径由 Mintlify 配置负责。资料来源：README.md:CHANGELOG 段 如升级后遇到文档与本地脚本不匹配的情况，建议重新执行安装流程以同步最新脚本与默认配置。

快速上手与初始化

ONBOARDING.md 为首次接入的贡献者准备了一条"阅读 → 安装 → 验证 → 提交"的推荐路径。资料来源：ONBOARDING.md:1-50 完成上述安装与初始化后，建议通过 package.json 中定义的 scripts 段验证本地环境是否就绪，例如运行构建、测试或健康检查脚本，确认 CLI 输出符合预期后再选择首个任务开始贡献。资料来源：package.json:scripts 段

架构概览与协作流程

ARCHITECTURE.md 描述了 ForgeKit 各子模块如何通过 bin/ 脚本与 npm 脚本协作，并解释了"安装 → 初始化 → 运行"这条主链路上的数据走向。资料来源：ARCHITECTURE.md:1-40 下面用 Mermaid 图展示从克隆到本地开发环境的整体流程：

flowchart LR
    A[克隆仓库] --> B[install.sh]
    B --> C[运行时与依赖]
    C --> D[bin/claude-init.sh]
    D --> E[项目骨架与配置]
    E --> F[本地开发环境]

由图可见，install.sh 与 bin/claude-init.sh 形成前后衔接的两阶段流水线：前者负责"环境就绪"，后者负责"工程初始化"，二者共同把一个空仓库转换为可运行的开发环境。后续若需要查看模块依赖关系或脚本调用链，应优先参考 ARCHITECTURE.md 而不是源码反推。资料来源：ARCHITECTURE.md:模块依赖段

Substrate（认知基座）是 forgekit 在执行任何实质性动作（mutation、副作用、外部调用等）之前必经的"闸门层"。它的核心职责不是执行任务本身，而是在动作发生之前完成一次完整的认知评估：界定边界、预测后果、评估冲击、选择路径，并决定放行、回退或重写。该模块对外暴露的是一个"行动前契约"（pre-action contract），让上层调用方能够在不可逆操作落地前获得确定性反馈。

资料来源：src/substrate.js:1-40

设计目标与作用域

Substrate 的设计目标可以概括为三点：

1. 可解释性：每一次放行都必须能回溯到具体的评估证据，而不是黑盒判断。
2. 可中断性：任何评估环节都可以否决当前请求，并且必须给出可读的拒绝原因。
3. 可组合性：评估步骤（scope → predictor → impact → route → preflight）应当彼此解耦，便于单独替换或注入新策略。

scope.js 负责在闸门最前端界定本次行动的"作用域"，例如资源边界、用户身份、时间窗口以及允许的副作用类别。它不评估后果，只负责把"我们正在讨论什么"讲清楚。资料来源：src/scope.js:1-30

核心组件与数据流

闸门的内部流水线由以下模块串联而成，每一个模块都对应一个明确的认知阶段：

• scope.js：界定边界，生成一个结构化的 Scope 对象作为后续评估的输入。
• predictor.js：基于 Scope 预测最可能的执行轨迹与潜在分支，输出一个预测集合。
• impact.js：将每条预测轨迹折叠为影响度量（成本、风险、可逆性、波及面）。
• route.js：根据影响度量在预设的策略表中选择执行路径（直接放行、降级执行、需要人工审批、拒绝）。
• preflight.js：在真正放行前再做一次轻量级干跑（dry-run），校验外部依赖与前置条件是否仍然成立。

整个数据流是一条单向流水线，Scope 对象是唯一贯穿所有阶段的"事实载体"。资料来源：src/route.js:1-50，src/impact.js:1-45

flowchart LR
    A[Action Request] --> B[scope.js<br/>界定边界]
    B --> C[predictor.js<br/>生成预测]
    C --> D[impact.js<br/>影响度量]
    D --> E[route.js<br/>路径选择]
    E --> F[preflight.js<br/>干跑校验]
    F -->|通过| G[放行]
    F -->|失败| H[回退/拒绝]

与上层调用方的契约

调用方提交的不是"要做什么"，而是"打算做什么 + 当前上下文"。Substrate 在收到请求后会返回一个判定结果对象，至少包含以下字段：

• verdict：allow / downgrade / review / deny 四态之一。
• reason：人类可读的判定理由。
• evidence：本次判定所引用的 Scope、预测轨迹与影响度量指针。
• route：当 verdict 为 allow 或 downgrade 时，给出实际采用的执行路径。

这种契约设计确保了即便闸门拒绝了一个动作，调用方也能据此重写、重试或上报，而不是收到一个神秘的错误码。资料来源：src/substrate.js:42-90

失败模式与可观测性

闸门自身也会失败。当 preflight.js 检测到外部依赖不可用、Scope 校验不通过或预测模块返回空集时，Substrate 会进入保守拒绝模式：宁可误拒，不可误放。所有拒绝事件都会带上 evidence，以便上层接入日志、追踪与策略审计系统。

值得注意的社区共识是：在 v0.27.3 之后，文档被统一为英文，自动化本地化路径也被记录在 #109 中。这意味着围绕 Substrate 的策略配置与失败原因应当以英文键名存储，而面向用户的提示文案才走本地化层，避免策略表与运行时之间出现键名漂移。资料来源：CHANGELOG.md:1-20

使用建议

• 把 scope.js 当作唯一可信输入源，不要在调用方侧重复拼接边界条件。
• predictor.js 与 impact.js 是性能热点，建议在生产环境中注入缓存与采样策略。
• route.js 的策略表是可热替换的，应通过配置中心而非代码修改来调整。
• 当 verdict 为 review 时，调用方应当把决策权移交给人工或上层审批流，而不是默默重试。

证明性记忆（PCM）、账本与团队同步

一套配置兼容所有 AI 编程助手——为 Claude Code、Codex、Cursor、Gemini、Aider 等提供跨工具配置与认知基座（记忆、爆炸半径、安全护栏）。

系统拓扑

下图展示了分发链路与可观测性反馈环的总体形态。init 负责登记工具，integrations 把 MCP 服务器接入运行时，update / sync 负责把变更推下去，verify 校验最终一致性，doctor 持续采集运行时信号并把异常回写到上游。

graph TD
  A["init.js<br/>工具初始化与登记"] --> B["integrations.js<br/>MCP 集成"]
  B --> C["update.js / sync.js<br/>分发与同步"]
  C --> D["verify.js<br/>一致性验证"]
  D --> E["doctor.js<br/>健康诊断"]
  E -.异常上报.-> B

多工具分发：init、sync 与 update

分发层关心「谁被安装、按什么顺序、用什么来源」三件事。init.js 是首次接触点，它读取本地配置清单、解析声明的工具集合，并把每个工具的标识符、版本、来源登记到 forgekit 内部的注册表。后续命令都依赖这份注册表，因此在初始化完成前其它子命令通常拒绝执行。

sync.js 与 update.js 形成一对互补命令：sync 偏向「把本地声明与远端清单对齐」，处理添加、移除、停用等结构性变更；update 则聚焦「在不改变拓扑的前提下把已有工具拉到目标版本」。两者的关键差异在于 sync 会修改注册表的成员资格，而 update 只触动版本字段。这样设计可以让用户分别审计「我装了哪些工具」与「我的工具是什么版本」。

资料来源：src/init.js:1-120 src/sync.js:1-200 src/update.js:1-180

MCP 集成：integrations 模块

integrations.js 是子系统中语义最重的一块。Forgekit 在这里把 MCP 当作一类特殊的「工具源」来处理：每个 MCP 服务器对应一个可寻址的端点，forgekit 在启动阶段探测其连通性、协商传输格式（stdio、HTTP、SSE 等），并把可用方法暴露成本地命令空间。模块同时维护一份能力清单，记录哪些方法被授权在当前 profile 下调用，避免把全部方法都注入运行时。

为了支持多 MCP 并存，integrations 在内部使用「优先级 + 命名空间」的二维路由：同名方法按优先级解冲突，不同命名空间的方法可以共存。这一抽象让 doctor 与 verify 可以按命名空间维度独立诊断。

资料来源：src/integrations.js:1-260

验证：verify 子系统

verify.js 的职责是给「分发成功」一个可证伪的定义。它在每次 update / sync 之后被自动调用，也可以由用户手动触发。验证分为三个层级：

verify 的输出是一份带签名的校验报告，供后续 doctor 增量比对使用，从而避免每次都做昂贵的全量重检。

资料来源：src/verify.js:1-220

可观测性：doctor 与诊断闭环

doctor.js 是整套子系统的「持续眼睛」。它周期性探测 MCP 端点延迟、工具调用成功率、注册表漂移，并把结果聚合为一份健康快照。doctor 不主动修改任何状态，只产出诊断数据；治理动作由用户结合 verify 报告与 update 命令显式执行。

在 v0.27.3 中，文档站点被收敛为英文，并补充了自动本地化路径说明（PR #109），这一变更不影响 doctor 的运行时行为，但使得诊断输出的国际化与文档同步更容易追踪。

资料来源：src/doctor.js:1-240 src/update.js:120-180

协作模式与典型流程

一次完整的多工具分发通常按以下顺序进行：先由 init 建立基线注册表，再用 integrations 注册并预热 MCP 端点，随后 update 拉取目标版本，最后 verify 出具校验报告。如果 doctor 在后台发现持续异常，会提示用户进入下一轮 sync → update → verify 的修复循环。这种「声明 → 分发 → 校验 → 观测」的四段式结构，使每个阶段都可以独立重放，便于在 CI 中复现问题。

资料来源：src/init.js:80-120 src/verify.js:150-220 src/doctor.js:200-240

Pitfall Log / 踩坑日志

项目：CodeWithJuber/forgekit

摘要：发现 7 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：配置坑 - 可能修改宿主 AI 配置。

1. 配置坑 · 可能修改宿主 AI 配置

• 严重度：medium
• 证据强度：source_linked
• 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
• 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
• 证据：capability.host_targets | https://github.com/CodeWithJuber/forgekit | host_targets=claude_code, claude, cursor, mcp_host

2. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 证据：capability.assumptions | https://github.com/CodeWithJuber/forgekit | README/documentation is current enough for a first validation pass.

3. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 证据：evidence.maintainer_signals | https://github.com/CodeWithJuber/forgekit | last_activity_observed missing

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 证据：downstream_validation.risk_items | https://github.com/CodeWithJuber/forgekit | no_demo; severity=medium

5. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 证据：risks.scoring_risks | https://github.com/CodeWithJuber/forgekit | no_demo; severity=medium

6. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 证据：evidence.maintainer_signals | https://github.com/CodeWithJuber/forgekit | issue_or_pr_quality=unknown

7. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 证据：evidence.maintainer_signals | https://github.com/CodeWithJuber/forgekit | release_recency=unknown