ark

ArkGate 是一套针对 AI 编写的 TypeScript 的导入规则。Contener · Guiar · Ordenar：限制 AI 可以写什么，以及写成什么样。引导下一步。让遗留的混乱逐渐归整，最终形成干净的目录树。

为什么

AI 会走最短的路。一条错误的导入落地，接着又来一条，产品就会越来越难以修改。等 Agent 完成后才运行的代码检查器，发现问题时已经太晚了。

在实现之前设计好边界。在工作前面加上一个小型接口，把细节留在它后面。如果仍有遗留问题，诚实的提示应该是需要重构。为了让检查变绿而放宽规则，只会让设计停留在未完成状态。

试用

一条命令。仅预览，不会更改任何文件。当前版本为 4.8.29 （使用 npm view arkgate version 检查 npm 上的 latest 版本）：

npx [email protected] start

检查结果为红色时会是什么样

规则文件创建后，如果领域文件导入了基础设施，检查就会失败（退出代码为 1）。这是 arkgate-check 在 [email protected] 上的实际输出：

✖ LAYER_IMPORT_VIOLATION  src/domain/order.ts:1
  DomainModel → Infrastructure  (src/infra/db.ts)
  DomainModel must not import Infrastructure.
  Next action: Classify the import: if it is constants/types/pure, adopt into DomainModel or SharedKernel; define a port only if the target is a real use-case. Then preflight again.

✖ 1 violation(s).

接下来就采取行动。对导入进行分类；如果依赖对应真实用例，就引入一个端口。然后再次运行检查。

这条红线就是检查。它不会阻止所有写入。在 Cursor 上，如果钩子没有设置 failClosed: true，就是故障开放：检查器无法运行时，写入仍会生效。Shell 写入、托管工具和人工编辑都不受本地钩子约束。适用于所有路径的硬性保障，是设为必需的 GitHub 状态检查，并运行 arkgate-check --strict-merge。在该状态检查成为必需项之前，规则文件就只是一份文档。

所有人：使用 ArkGate · 开发者：开发 · 本库：贡献指南

---

附录

上面的简要介绍就是产品。下面是参考资料：更完整的介绍、产品不是什么、支持的宿主、命令、额外功能，以及发布历史所在位置。

选择你的路径

你是……	前往
任何人（借助 AI 交付，尽量少用术语）	使用 ArkGate
开发者（宿主、CI、配置、棕地项目）	使用 ArkGate 进行开发
贡献者（改进本库）	贡献指南

完整导航：docs/README.md

更完整的介绍

AI 能快速构建，也能同样快速地制造混乱。

让产品易于理解、修改和值得信赖。

限制 AI 可以写什么，以及写成什么样。用经过验证的模式和下一步行动为你指引方向。让遗留的混乱逐渐归整，最终形成干净的目录树。

让变更更安全、意外更少，并且只在你选择时提供额外保护。

这就是 Contener · Guiar · Ordenar。

本项目不是什么

它不是 API 网关，也不是目录检查器。如果检查没有设为拉取请求的必需项，配置就只是一份文档。

ArkGate 不是 Web 框架、ORM 或任务运行器。npm 包名是 arkgate，与独立的 Archgate CLI 项目无关。

ArkRun 是可选的实验性运行时，使用内存存储，不是 Postgres。@arkgate/runtime 已弃用。ArkOrder 不能取代导入规则：即使层级检查全绿，Agent 仍可能把计费方案重写成按席位计数。

它是什么

  src/domain/order.ts
       │  import { db } from "../infra/postgres"
       ▼
  ┌──────────────────────────────────────────┐
  │  CHECK                                   │
  │  Domain ─✕─▶ Infrastructure              │
  │  write doesn't land · PR check fails     │
  └──────────────────────────────────────────┘

当 Agent 写入错误的导入时，写入不会生效。 同一项检查也会让拉取请求失败。这就是 ArkGate——一旦采用（Contener），导入规则就会始终启用。其他三项均为可选。

	作用	时机
Agent 写入时	在受支持的主机上，写入不会生效；在其他主机上仅发出警告	始终启用（ArkGate）
合并前	将 arkgate-check 设为必需的 CI 状态	始终启用（ArkGate）
ArkRules	层内的可选策略（Contener — 结构）	按需启用
ArkRun	可选的实验性运行时（arkgate/runtime）（Guiar）	除非手动启用，否则关闭
ArkOrder	针对少数重大选择的额外功能——计费方案，而非席位数（arkgate/order）（Ordenar）	除非手动启用，否则关闭

层（谁可以导入谁）始终运行。缺少 ArkRules、ArkRun 和 ArkOrder 时，不会改变层间判定。将遗留问题标记为 [Layer]、[ArkRules]、[ArkRun] 或 [ArkOrder]。 详情：配置 · 使用。

  ┌─────────┐     ┌─────────┐     ┌─────────┐
  │  WRITE  │────▶│  CHECK  │────▶│  SHIP   │
  │  agent  │     │  block  │     │  merge  │
  └─────────┘     └────┬────┘     └─────────┘
                       │
                       ▼
                 bad import
                 doesn't land

采用意味着设置一个必需的 GitHub 状态，运行 arkgate-check --strict-merge；或者明确采用 advisory-only 立场。状态信息简洁（arkgate-check --doctor；使用 --all 查看详情）。

何时不应采用

对于没有 AI Agent且没有多层边界的小型代码树、没有集成压力的单人爱好型 CRUD 项目，以及不愿维护 ark.config.json 或运行 arkgate-check --strict-merge 的必需 CI 状态的团队，ArkGate 都显得过于复杂。没有该状态，规则文件就只是文档——只使用边界检查工具即可（参见为何不只用 ESLint / Nx / cruiser？）。 适用于所有人的说明：docs/use.md — 何时不应采用。绿灯检查的局限：4.3.0 — ArkGate 是什么／不是什么。

---

状态指示灯（不是设置）

  [ Setup ] ──▶ [ In progress ] ──▶ [ Ready ]
                                      │
                                      └── Ready · needs a refactor

指示灯	含义	应采取的措施
Setup	代码树规模小／较新	完成 start → 状态
In progress	尚未完全受到保护	状态操作 #1
Ready	导入边界清晰，且与合并基准相比没有新增 UI 业务规则文件	保留写入路径 + CI
Ready · needs a refactor	边界清晰；仍有设计工作待完成	做一项小改动——不要说“完成了”

详情：docs/use.md。

---

一分钟上手

npx arkgate start                 # preview files + commands
npx arkgate start --apply         # compact config + host router + CI plan
npx --package=arkgate arkgate-check --doctor        # status — one next step
npx --package=arkgate arkgate-check --doctor --all  # full details

start --apply 会使用此仓库的包管理器（在工作区根目录运行 pnpm add -w / yarn add -W）固定安装 arkgate。在 workspace:* 根目录不要运行 npm install -D arkgate——npm 不接受该协议。在本地安装后，npx arkgate-check --doctor 也能正常使用。arkgate-check 是 arkgate 包中的命令，不是独立的 npm 包。如果 pnpm Age（minimumReleaseAge）阻止安装全新发布的版本，请继续使用 npx --package=arkgate@<version>——不要重复运行相同的 add 命令。在 pnpm 配置或 pnpm-workspace.yaml 中将 arkgate 加入 minimumReleaseAgeExclude（仅使用 CLI 标志并不足够），或者等该包发布一段时间。

如果预计纳入治理的覆盖率低于 50%，或形态置信度较低（覆盖率低于 80% 时低于 0.6），或者计划写入的内容对紧凑模式启动来说过大（超过 8 个 gate 文件或 32 KB），start --apply 会拒绝执行。这是有意设置的限制。覆盖率／形态：使用 --archetype <id>、--preset <name> 或 --force 锁定。大小：--force 无法解除此限制。下一步：npx arkgate-check --init。或者使用 npx arkgate-check --recommend 查看排序后的形态。

以上是更完整的流程。遇到问题？运行 status（--doctor），并执行操作 #1。

start → doctor → new files in the right folder
              ↘ leftover mess: map, then one small refactor

不要在产品 PR 中包含规则文件。本地检查： ark-check --local --base origin/dev（等同于 --changed；与 --strict-merge 同时使用时会被拒绝）。如需更改规则本身，请使用 --contract-session。

别名 ark / ark-check / ark-mcp 仍可使用。支持 npm / pnpm / yarn。没有安装生命周期脚本 ——pack 或 prepare 时也不会运行脚本，因此 pnpm add git+https://github.com/pedroknigge/arkgate 可在固定的提交上安装，无需 allowBuilds 条目。通过 Git 安装会提供 CLI 和 schema；库、MCP 和 ESLint 入口位于构建后的 dist/ 中，并通过 npm 提供。 请参阅 docs/package-surface.md。

---

主机强制执行支持

主机	本地写入边界	MCP 验证	CI / 合并路径	修复载荷
Claude Code	安装并信任后，对列出的操作（PreToolUse Write / Edit / MultiEdit）进行硬拦截	提示性；必须由 Agent 调用	运行 arkgate-check --strict-merge（别名 ark-check）的必需 GitHub 状态检查上下文	Hook 拒绝时发出；主机必须重新注入（安装并信任后走硬拦截路径）
Grok Build	安装并信任后，对列出的操作（PreToolUse write / search_replace（及其别名））进行硬拦截	提示性；必须由 Agent 调用	运行 arkgate-check --strict-merge（别名 ark-check）的必需 GitHub 状态检查上下文	Hook 拒绝时发出；主机必须重新注入（安装并信任后走硬拦截路径）
Google Antigravity	安装并信任后，对列出的操作（PreToolUse write_to_file / replace_file_content / multi_replace_file_content）进行硬拦截	提示性；必须由 Agent 调用	运行 arkgate-check --strict-merge（别名 ark-check）的必需 GitHub 状态检查上下文	Hook 拒绝时发出；主机必须重新注入（安装并信任后走硬拦截路径）
Cursor	安装并信任后，对列出的操作（preToolUse Write / StrReplace）进行硬拦截	提示性；必须由 Agent 调用	运行 arkgate-check --strict-merge（别名 ark-check）的必需 GitHub 状态检查上下文	可能会发出信封（--hook-repair）；不保证重新注入
OpenAI Codex	安装并信任后，对列出的操作（Codex CLI 和本地 ChatGPT Desktop/App Server 中的 PreToolUse apply_patch）进行硬拦截	提示性；必须由 Agent 调用	运行 arkgate-check --strict-merge（别名 ark-check）的必需 GitHub 状态检查上下文	可能会发出信封（--hook-repair）；不保证重新注入
OpenCode	写入时采取提示性 / 尽力而为的拦截（MCP + 可选插件；不是硬边界）	提示性；必须由 Agent 调用	运行 arkgate-check --strict-merge（别名 ark-check）的必需 GitHub 状态检查上下文	无硬边界载荷

CI 列的含义： 对所有主机而言，整个仓库范围内的硬性保障，是运行 CLI 的必需 GitHub 状态检查上下文，而不是“CI 文件存在”，也不只是 CLI 二进制文件名。 Codex 的硬写入拦截仅覆盖完整的本地 apply_patch；Cursor 仅覆盖启用了 failClosed: true 的所列 preToolUse 操作。不带该标志的 Cursor Hook 会在故障时放行 （如果检查器无法运行，写入仍会生效）。这两种情况下，都必须安装并信任项目 Hook；而 Shell / 直接 文件系统写入、托管或专用的选择退出路径，以及人工编辑，仍依赖 CI。

此表说明的是安装文件且主机已加载并信任这些文件后的受支持配置。硬性本地边界仅覆盖所列的 Hook 操作；其他工具、直接文件系统写入和人工编辑仍依赖 CI。写入门控顺序：先安装并信任主机预 Hook。缺少该路径或其在故障时放行时，再由 MCP prepare 作为后备。MCP 验证仅是提示性的，因为必须由 Agent 调用。只有当仓库将该状态检查设为必需时，CI 检查才会阻止合并。可能会发出修复信封，但不保证重新注入；绝不会静默自动应用。运行 arkgate-check --doctor（或 ark-check --doctor）以查看当前仓库中实际检测到的证据。

为什么必需 CI 是不可逾越的底线

上述划分是有意为之的权衡，并非缺失。ArkGate 会在每个宿主提供的最早边界进行验证，并在仓库可以设为不可绕过的最早边界强制执行：必需的合并状态。强制钩子（Claude Code、Grok Build、Google Antigravity、Cursor，以及 Codex 的完整本地 apply_patch）会在写入时拒绝其列出的写操作；建议性入口（MCP、规则、OpenCode 插件）则会在 Agent 工作时向其发出警告。但任何本地边界都可能被绕过——改用其他工具、托管／专用路径、直接写入文件系统，或由人工编辑——因此 ArkGate 对所有路径唯一承诺的保障就是 arkgate-check --strict-merge 检查，而且只有在仓库将该状态设为必需时才成立。本地检查旨在加快反馈；正确性由必需 CI 负责。

由此带来的一个实用结果是：规则文件也能充当压力传感器。若违规反复出现，或基线例外集中在某个层边界，就说明当前设计已不再适配代码——这表明应有意调整规则（从 /ark-explore 开始），而不是削弱检查。

各宿主的设置：docs/ai-gates.md · 开发路径：docs/develop.md

如需权威的 MCP 契约证据，请使用准确的项目根目录调用 ark_identity，然后使用该根目录和返回的项目 ID 调用 ark_manifest。位于项目目录内的后代路径必须提供匹配的 ID。旧版 ark://manifest 资源仅用于兼容，且始终未经验证、非权威，因为标准的 resources/read 无法以可移植的方式传递此预期。

---

为什么不只用 ESLint / Nx / cruiser？

	ArkGate	典型的边界检查工具
CI 导入规则	✅	✅
在受支持的宿主上硬性阻止 AI 写入	✅	❌
Agent 可读取的项目绑定规则（ark_manifest）	✅	❌
多文件变更的放置规则 + 预检	✅	❌
真实的受治理比例 + 双重规划（边界与结构）	✅	❌
可选的层内 ArkRules（结构 + 不变量）	✅	❌
阻止重新编写账单计划这类重要产品决策（ArkOrder）	✅	❌
分析不完整时不会显示为绿色	✅	不一

---

常用命令

npx arkgate start --apply
npx arkgate status --json          # session/project snapshot (identity, activation, last check)
npx arkgate-check --doctor
npx arkgate-check --plan
npx arkgate-check --coverage
npx arkgate-check --path-drift --base-ref origin/main   # stale paths in strings/comments after a rename
npx arkgate-check --sensors        # which sensors can EVER be enforced, and which of your rules can be promoted
npx arkgate-check --promote        # what enforcing each advisory rule would cost, from one run
npx arkgate-check --strict-merge   # CI / required status
npx arkgate-check --install-agent-gates --tools claude,cursor,codex,grok,antigravity
# optional: refresh shared home skills (Claude/Grok/Antigravity/Codex; never downgrades)
# npx arkgate-check --install-agent-gates --skills-only --agent-homes --force
# optional: closed skill catalog via Agent Skills ecosystem (ARK_SKILL_NAMES)
# npx skills add ./node_modules/arkgate/templates/agent-skills
# optional ArkRun: poll the loopback inspector (ANSI TUI — not a gate)
# npx ark-dashboard --url http://127.0.0.1:<port>/snapshot

更多信息：docs/develop.md · skills 安装：docs/agent-guide.md · 爱好者路线：docs/enthusiast/

其他 skills，仅在需要时使用

日常工作使用精简的路由器和状态。完整的 /ark-* 套件面向专家：当你需要引导式的下一步时再安装，而不是一开始就使用。目录和安装路径：安装 skills — Ark 及其生态系统。

---

可选的 ArkRun

门禁不需要应用运行时。除非你想使用可选运行时来实现解耦，否则可以跳过此部分。

ArkRun（arkgate/runtime，同一 npm 包）就是这样的运行时。每次调用 createStrictArkKernel() 都会创建一个新实例——没有进程级单例。数据驻留在内存中，重启后即消失。适合本地使用。它不是 Postgres，不是 outbox，也不是 Temporal。@arkgate/runtime 已弃用。

开发检查器和可观测性仪表板

选择启用的 startInspector() 仅绑定到环回地址（127.0.0.1），在 NODE_ENV=production 时会拒绝启动，并提供 JSON 信息——而非 TUI。除 GET /snapshot、GET /events（SSE）和 GET /graph 外，检查器还提供队列监控：

路径	响应体（JSON）
GET /outbox	待处理/失败的 outbox 摘要及计数（available、pendingCount、failedCount、pending、failed）——不包含事件负载
GET /workflows	工作流摘要及计数（available、total、runningCount、…、workflows）

通过双 bin ark-dashboard / arkgate-dashboard （bin/ark-dashboard.mjs）轮询这些信息。仅使用 ANSI 和轮询（不使用 React/Ink/Blessed）。将 --url / -u 指向检查器（handle.url 或 handle.snapshotUrl）；仪表板 也会获取同级的 /outbox 和 /workflows。startInspector() 会绑定随机端口， 除非传入 { port }，因此备用地址 http://127.0.0.1:3000/snapshot（或 ARK_DASHBOARD_URL）仅适用于 startInspector({ port: 3000 })。--interval / -i 会限制在 200–60000 毫秒之间（默认值为 2000）；支持 --once、--help、--version。 也可使用 ark dashboard / arkgate dashboard（转发到同一个 bin）。内核保持 仅输出 JSON；展示逻辑留在 bin/ 中。

持久性立场

默认存储（InMemoryEventBuffer、InMemoryAuditStore、InMemoryReadModelStore、 InMemoryWorkflowStore）仅为内存中的参考实现。适用于测试。它们 无法在重启后保留数据，也不具备生产级持久性。生产环境请接入真实的存储 接口。详情：docs/production-hardening.md。

---

可选的 ArkOrder

分层可以阻止不良导入。ArkOrder 可以避免把大型产品选择（例如计费方案） 当作席位数量来反复改写。通过阀门更改这些选择，而不是使用通用更新。

除非添加 arkOrder，否则默认关闭。使用同一个 npm 包（arkgate/order）。基于内存。 不是服务。不会替代 ArkGate 或 ArkRun。

指定少数选择项（xiKeys：方案、周期、租户模式——而非席位数量）。首次 冻结使用 release()。之后更改则使用 proposeRelease，再调用 apply。通用 update 不会生效。

验证示例（GitHub，而非 npm 压缩包）： examples/arkorder-billing ——首次冻结使用 release()；之后更改方案则使用 proposeRelease，再调用 apply。 示例索引： examples/README.md。 精简入门示例会关闭此额外功能。详情：ArkOrder。

---

文档

读者	链接
文档中心	docs/README.md
所有人	docs/use.md
集成 ArkGate 的开发者	docs/develop.md
本库的贡献者	CONTRIBUTING.md
宿主安装详情	docs/ai-gates.md
配置 · 包接口 · TS	configuration · package-surface · typescript-support
棕地项目	docs/brownfield-adoption.md
安全	SECURITY.md
发布历史	CHANGELOG.md · 网站更新日志 · 文档中心索引
历史记录 / 维护者依据	docs/archive/

版本说明见 CHANGELOG.md 和网站更新日志。文档中心保留了按版本整理的索引：历史记录和维护者资料。

---

为此库做贡献

git clone https://github.com/pedroknigge/arkgate
cd arkgate && npm ci && npm run build
npm test && npm run check:architecture

完整指南：CONTRIBUTING.md · 待办列表：ROADMAP.md

---

网站： arkgate.online · npm： arkgate
MCP： io.github.pedroknigge/arkgate
Node ≥ 18 · MIT

Ark 不会替你发明产品。它会拒绝非法写入，并在它实际上尚未真正实施任何约束时告诉你。