项目定位与背景

Hecateq OpenAgent 是一个面向 OpenCode 生态的 AI 代理编排插件，基于 oh-my-openagent 进行深度定制，旨在与 Hecateq 代理工作流引擎协同工作。当前首个 Beta 版本为 v0.1.0-hecateq.1，重点引入任务图编排、自愈式记忆管理、校验护栏等能力。仓库根目录的 package.json 中明确声明了关键字 opencode、openagent、ai-agents、agent-orchestration 以及 hecateq，许可证为 SUL-1.0，由此可确认其作为生产级代理插件的定位。资料来源：package.json:1-30

整个仓库采用 monorepo 形式组织，根级 package.json 的 scripts 字段中通过 tsgo --noEmit 对十余个子包（rules-engine、ast-grep-core、ast-grep-mcp、model-core、comment-checker-core、hashline-core、boulder-state、agents-md-core 等）统一进行类型检查，体现了多包协同与强类型约束的开发范式。资料来源：package.json:1-20

仓库结构与核心包组成

仓库以 packages/* 为基本单位划分职责清晰的功能模块。下表罗列了若干关键包及其角色定位：

架构关系图

graph TD
  OC[OpenCode 宿主] --> HO[Hecateq OpenAgent 插件]
  HO --> LSP[packages/lsp-tools-mcp]
  HO --> RULES[packages/rules-engine]
  HO --> MODEL[packages/model-core]
  HO --> HASH[packages/hashline-core]
  HO --> BG[packages/boulder-state]
  LSP --> MCP[(stdio MCP Server)]
  MODEL --> CAP[能力快照 + 回退链]
  RULES --> FS[项目目录 .omo/.claude/.cursor]

如架构图所示，Hecateq OpenAgent 在 OpenCode 宿主之上以插件形态聚合多个项目，对外通过 MCP 协议（如 LSP 工具）和文件规则系统（.omo/rules、.claude/rules 等）向代理运行时提供上下文。rules-engine 内部通过 SOURCE_PRIORITY 维护了一套严格的规则源优先级，例如 .omo/rules 优先级为 0，~/.omo/rules 为 100，从而保证项目级规则优先于用户全局规则。资料来源：packages/rules-engine/src/constants.ts:1-30

关键能力概览

模型解析与回退链

model-core 是整个项目的“模型大脑”，对外暴露模型解析、规范化、能力探测、回退链构造等能力。index.ts 中集中重导出 resolveModel、resolveModelWithFallback、normalizeFallbackModels、flattenToFallbackModelStrings 等核心函数，并附带 ModelResolutionRequest、ModelResolutionResult 等类型契约。资料来源：packages/model-core/src/index.ts:1-20

model-requirements.ts 以代理（agent）维度声明了 AGENT_MODEL_REQUIREMENTS，例如 sisyphus 代理的回退链包含 claude-opus-4-7（max 变体）作为首选项，并按序回退至 gpt-5.5（high）、k2p5 等模型。unspecified-low 类别则依次尝试 claude-sonnet-4-6、gpt-5.3-codex（medium）、kimi-k2.6、gemini-3-flash 等候选。known-variants.ts 中维护了标准变体集合 KNOWN_VARIANTS（low、medium、high、xhigh、max、minimal、none、auto、thinking），用于变体词法识别。资料来源：packages/model-core/src/model-requirements.ts:1-30、packages/model-core/src/known-variants.ts:1-10

能力探测方面，get-model-capabilities.ts 通过 diagnostics 字段追踪每个能力字段的来源（runtime / override / heuristic / snapshot），例如 supportsThinking 的来源会按 override > heuristic > runtime > snapshot > none 的顺序回退。getModelCapabilities 最终返回的 canonicalModelID、reasoning、toolCall、modalities 等字段，可被上层调度器直接消费。资料来源：packages/model-core/src/model-capabilities/get-model-capabilities.ts:1-40

LSP 工具与 MCP 集成

lsp-tools-mcp 作为一个独立的 stdio MCP 服务，对外提供 lsp_diagnostics、lsp_goto_definition、lsp_find_references、lsp_symbols、lsp_prepare_rename、lsp_rename、lsp_status 等工具，被 Hecateq OpenAgent 注册为 Tier-1 内置 MCP。其 README 明确指出：上游 codex-lsp 与 oh-my-openagent 都以 git submodule 方式消费本仓库，修改请提交至本仓库。资料来源：packages/lsp-tools-mcp/README.md:1-20

language-mappings.ts 中维护了从文件扩展名到 LSP 语言 ID 的映射表，覆盖 python、typescript、rust、haskell、terraform、typst、kotlin、graphql 等 60+ 种语言。types.ts 则定义了与 LSP 协议对齐的 Diagnostic、TextEdit、WorkspaceEdit、PrepareRenameResult 等结构。资料来源：packages/lsp-tools-mcp/src/lsp/language-mappings.ts:1-30、packages/lsp-tools-mcp/src/lsp/types.ts:1-20

规则发现与优先级

rules-engine 的 constants.ts 集中描述了项目识别（PROJECT_MARKERS）、规则子目录（PROJECT_RULE_SUBDIRS）、用户级规则目录、规则文件后缀（.md / .mdc）以及源优先级。AGENTS_FILENAME 指向通用的 AGENTS.md，GITHUB_INSTRUCTIONS_PATTERN 形如 /\.instructions\.md$/，用于识别 GitHub Copilot 指令文件。EXCLUDED_DIRS 显式排除 node_modules、.git、dist、build、.turbo、.next、coverage 等构建产物目录，避免误加载。资料来源：packages/rules-engine/src/constants.ts:1-20

技术栈与开发约定

• 语言与运行时：TypeScript（tsgo 编译）、Bun 测试与脚本执行、根级 package.json 与各子包 package.json 共同约束 ESM 模块。资料来源：package.json:1-20
• Web 前端：packages/web 使用 Next.js 15.5.18、React 19.2.6、next-intl、@radix-ui、tailwind-merge、lucide-react、marked 等组件栈，构建产物通过 opennextjs-cloudflare 部署到 Cloudflare。资料来源：packages/web/package.json:1-20
• 代码质量：biome check 负责 lint/format，tsgo --noEmit 负责类型检查，bun test 运行单元测试（如 model-requirements.test.ts、model-capabilities.test.ts 中覆盖回退链顺序、变体识别、能力源追踪等关键不变量）。资料来源：package.json:1-20、packages/model-core/src/model-requirements.test.ts:1-30

常见使用与排错要点

1. 修改 LSP 工具请回上游：所有 LSP 行为变更应提交到 lsp-tools-mcp，下游通过子模块指针升级，避免在多个仓库中重复维护运行时。资料来源：packages/lsp-tools-mcp/README.md:1-20
2. 模型回退链调整：若需新增代理或修改优先级，请同时调整 AGENT_MODEL_REQUIREMENTS 与 CATEGORY_MODEL_REQUIREMENTS，并补充对应的 model-requirements.test.ts 断言。资料来源：packages/model-core/src/model-requirements.test.ts:1-30
3. 规则冲突排查：当多源规则同时命中时，以 SOURCE_PRIORITY 数值为准；项目内 .omo/rules（优先级 0）始终高于用户级 ~/.omo/rules（优先级 100）。资料来源：packages/rules-engine/src/constants.ts:1-30

参见

• LSP 工具与 MCP 集成
• 模型解析与回退链
• 规则引擎与项目规则发现
• Hashline 锚点编辑

概述

Lib 模块 位于 packages/web/lib/ 目录，是 Hecateq OpenAgent 文档站点的核心工具层。它位于 Next.js 15 页面路由与底层数据源之间，为文档渲染、统计聚合、章节划分以及通用工具函数提供共享能力。该模块的设计哲学是“服务端生成 + 客户端轻引用”，即文档内容在构建阶段通过脚本生成，运行期只需按需加载。

资料来源：packages/web/package.json:1-50

文件结构与职责

下表总结了 packages/web/lib/ 下常见文件及其职责（基于仓库源码与 package.json 中的脚本入口推断）：

资料来源：packages/web/lib/docs-source.ts:1-7

文档加载机制

docs-source.ts 是文档站点与底层内容之间的桥梁。其实现仅有 8 行：

import { DOC_SOURCES } from "./docs-content.generated"

export function loadDocSource(file: string): string {
  const source = DOC_SOURCES[file]
  if (source === undefined) {
    throw new Error(`Unknown doc file: ${file}`)
  }
  return source
}

关键点：

• 生成期常量：DOC_SOURCES 由 scripts/generate-docs-content.mjs 在每次 type-check 前生成，避免运行期文件 I/O。package.json 中的 type-check 脚本会先调用 node ./scripts/generate-docs-content.mjs 再执行 tsgo --noEmit。
• 强类型映射：因为 DOC_SOURCES 是生成出来的 TypeScript 模块，IDE 可以提供自动补全与类型校验。
• 失败语义：当传入未注册的 file 时，函数主动抛出 Error，便于在开发阶段快速发现路径拼写错误。

资料来源：packages/web/lib/docs-source.ts:1-8；packages/web/package.json:24

与其他模块的协同

Lib 模块 并非孤岛，它与上层页面以及同仓库的若干核心包共同组成文档生态：

flowchart LR
    A[Markdown 源文件] --> B[scripts/generate-docs-content.mjs]
    B --> C[docs-content.generated.ts]
    C --> D[lib/docs-source.ts<br/>loadDocSource]
    D --> E[Next.js 页面]
    F[lib/docs-sections.ts] --> E
    G[lib/stats.ts] --> E
    H[lib/utils.ts] --> E
    E --> I[浏览器渲染]

• 文档渲染：页面通过 loadDocSource(file) 拉取原文，结合 marked（在 packages/web/package.json 中作为依赖引入）解析为 HTML。
• 导航分组：docs-sections.ts 负责把多份文档组织成章节，驱动侧边栏。
• 统计信息：stats.ts 与 utils.ts 提供首页指标卡所需的数据与样式辅助函数。

资料来源：packages/web/package.json:14-43

边界与扩展注意

虽然 Lib 模块 主要服务 web 端，但其命名风格与 packages/model-core、packages/rules-engine 等保持一致。理解下面这些“边界”有助于二次开发：

• 不要直接修改 docs-content.generated.ts：它是脚本产物，编辑后会被覆盖。
• 新增文档：需让 generate-docs-content.mjs 扫描到该文件，并在生成列表中正确登记。
• 类型安全：新增 lib 函数时，请复用 packages/model-core/src/index.ts 中已经导出的能力，例如 resolveModel、flattenToFallbackModelStrings 等，避免重复实现。
• 跨包配置常量：项目统一在 packages/rules-engine/src/constants.ts 定义 PROJECT_MARKERS、EXCLUDED_DIRS 等枚举，web 端如需复用规则相关常量，应通过包间依赖导入而非复制粘贴。

资料来源：packages/rules-engine/src/constants.ts:1-20；packages/model-core/src/index.ts:1-50

常见错误与排查

资料来源：packages/web/lib/docs-source.ts:1-8

See Also

• LSP Tools MCP 包
• Model Core 解析器
• Rules Engine 常量
• Hecateq OpenAgent 主页

Src 模块 是 Hecateq OpenAgent 多包仓库中各功能包内部的源代码根目录集合。仓库采用 monorepo 结构,每个子包(如 model-core、lsp-tools-mcp、rules-engine、hashline-core 等)的实现代码统一放在其自身的 src/ 子目录下,负责核心业务逻辑、模型解析、LSP 协议桥接、规则发现以及文档加载等不同职责。本页基于仓库中可读的源码文件,对主要 src 模块的功能边界、关键导出与典型用法进行梳理。

模块总览

下表汇总了本次审查范围内各 src 模块的核心定位(表格内容均直接来源于对应的 package.json 与源码导出):

model-core/src:模型解析与回退链核心

packages/model-core/src/index.ts 是整个 model-core 包的统一入口,聚合了模型需求、能力别名、能力启发式、能力护栏、解析器、规范化器、解析管线与回退链构建器等子模块。资料来源:packages/model-core/src/index.ts:1-50。

已知变体与回退链解析

known-variants.ts 定义了一个枚举性的 KNOWN_VARIANTS 集合,包含 low、medium、high、xhigh、max、minimal、none、auto、thinking,这是解析 claude-opus-4-7 max 或 gpt-5.5 high 等带后缀变体字符串时唯一被识别的合法 token。资料来源:packages/model-core/src/known-variants.ts:1-12。

fallback-chain-from-models.ts 中的 parseFallbackModelEntry 利用上述集合,将诸如 "claude-opus-4-7 (high)" 或 "gpt-5.5 high" 的字符串拆解为 { providers, model, variant } 三元组,然后交给 normalizeFallbackModels 做规范化。资料来源:packages/model-core/src/fallback-chain-from-models.ts:1-30。这意味着在 model-requirements.ts 中可以为同一模型声明多个变体级别,从而在主模型不可用时优雅降级。

模型需求与解析结果类型

model-requirements.ts 定义了 AGENT_MODEL_REQUIREMENTS 与 CATEGORY_MODEL_REQUIREMENTS,按代理(如 oracle、sisyphus)和能力类别声明回退链。例如 sisyphus 的回退链长度为 8,且显式排除 github-copilot 作为 gpt-5.3-codex 的 provider。资料来源:packages/model-core/src/model-requirements.ts:1-40。

model-resolution-types.ts 暴露了请求、来源与结果的强类型契约:ModelResolutionRequest 携带意图、可用模型约束与可选策略;ModelResolutionResult 标注结果模型与其 provenance(override / category-default / provider-fallback / system-default)。资料来源:packages/model-core/src/model-resolution-types.ts:1-30。

模型能力快照

model-capabilities/get-model-capabilities.ts 实现了一个分层回退机制:runtime 检测 > override > 启发式 > snapshot。每项能力(如 reasoning、supportsThinking、supportsTemperature、maxOutputTokens、toolCall、modalities)都附带 diagnostics.source 字段,标记该值来自哪一层,便于在生产环境中追溯。资料来源:packages/model-core/src/model-capabilities/get-model-capabilities.ts:1-50。

flowchart LR
  A[ModelResolutionRequest] --> B[resolveModel]
  B --> C{可用模型?}
  C -- 是 --> D[返回 ModelResolutionResult]
  C -- 否 --> E[按 fallbackChain 顺序尝试]
  E --> F[normalizeFallbackModels]
  F --> G[回退到 systemDefaultModel]
  G --> D

lsp-tools-mcp/src:LSP 协议到 MCP 的桥接

packages/lsp-tools-mcp/src/lsp/language-mappings.ts 维护了一个扁平的扩展名到 LSP 语言 ID 的映射表(如 .ts → typescript、.py → python、.rs → rust),供 LSP 客户端在请求时按打开文件的扩展名选择对应后端。资料来源:packages/lsp-tools-mcp/src/lsp/language-mappings.ts:1-40。

packages/lsp-tools-mcp/src/lsp/types.ts 定义了与 LSP 规范对齐的 TypeScript 类型,涵盖 Diagnostic、TextEdit、WorkspaceEdit、PrepareRenameResult 等核心结构,并暴露 SeverityFilter 类型("error" | "warning" | "information" | "hint" | "all"),便于上层工具按严重等级过滤诊断信息。资料来源:packages/lsp-tools-mcp/src/lsp/types.ts:1-40。

根据 packages/lsp-tools-mcp/README.md 的说明,该模块作为上游单一可信源,通过 git submodule 方式被 codex-lsp 与 oh-my-openagent 同时消费。资料来源:packages/lsp-tools-mcp/README.md:1-20。

周边 src 模块

rules-engine/src

rules-engine 包的 src/constants.ts 集中声明了规则发现所需的所有静态常量,包括项目标记(PROJECT_MARKERS)、规则子目录优先级(.omo/rules → .claude/rules → .cursor/rules → .github/instructions → .sisyphus/rules)、规则文件扩展名(.md 与 .mdc)、AGENTS.md 文件名常量,以及需排除扫描的目录集合(node_modules、.git、dist、build、.turbo、.next、coverage)。SOURCE_PRIORITY 用数值方式强制排序,数值越小优先级越高。资料来源:packages/rules-engine/src/constants.ts:1-30。

hashline-core/src

packages/hashline-core/package.json 声明该包为纯 TypeScript 实现,提供基于哈希锚点的编辑能力(典型应用场景是让模型在多次编辑同一文件时仍能精确定位行)。其依赖仅 diff,因此适合作为底层无副作用的工具被其他包复用。资料来源:packages/hashline-core/package.json:1-15。

web/lib

packages/web/lib/docs-source.ts 通过 loadDocSource(file) 加载由 scripts/generate-docs-content.mjs 预生成的 DOC_SOURCES 字典,使得 Next.js 构建产物在运行时无需再做 IO 即可渲染说明文档。资料来源:packages/web/lib/docs-source.ts:1-7。

社区关注点映射

首个 Beta 版本(v0.1.0-hecateq.1)中强调的"任务图编排、自我修复的记忆管理、稳健的校验防护",在 src 模块层面分别落地为:任务图编排依赖 model-resolution-pipeline 的 fallback chain;记忆管理的稳定性来自 model-resolver 与 model-sanitizer 的字符串归一化;校验防护则由 model-capability-guardrails 与 model-error-classifier 在 model-core 入口处统一把关。资料来源:packages/model-core/src/index.ts:1-50。

参见

• LSP 工具 MCP
• Rules Engine
• Hashline Core
• Model Core 解析管线

Pitfall Log / 踩坑日志

项目：hecateq/hecateq-openagent

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

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

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

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

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

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

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

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

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

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

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

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

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

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