# https://github.com/hecateq/hecateq-openagent 项目说明书 生成时间：2026-06-21 01:23:40 UTC ## 目录 - [项目概览](#page-overview) - [Lib 模块](#page-packages-web-lib) - [Src 模块](#page-packages-model-core-src) - [Src 模块](#page-packages-lsp-tools-mcp-src) ## 项目概览 ### 相关页面 相关主题：[Lib 模块](#page-packages-web-lib)
相关源码文件 以下源码文件用于生成本页说明： - [package.json](https://github.com/hecateq/hecateq-openagent/blob/main/package.json) - [packages/lsp-tools-mcp/README.md](https://github.com/hecateq/hecateq-openagent/blob/main/packages/lsp-tools-mcp/README.md) - [packages/lsp-tools-mcp/package.json](https://github.com/hecateq/hecateq-openagent/blob/main/packages/lsp-tools-mcp/package.json) - [packages/lsp-tools-mcp/src/lsp/language-mappings.ts](https://github.com/hecateq/hecateq-openagent/blob/main/packages/lsp-tools-mcp/src/lsp/language-mappings.ts) - [packages/lsp-tools-mcp/src/lsp/types.ts](https://github.com/hecateq/hecateq-openagent/blob/main/packages/lsp-tools-mcp/src/lsp/types.ts) - [packages/rules-engine/src/constants.ts](https://github.com/hecateq/hecateq-openagent/blob/main/packages/rules-engine/src/constants.ts) - [packages/model-core/src/index.ts](https://github.com/hecateq/hecateq-openagent/blob/main/packages/model-core/src/index.ts) - [packages/model-core/src/model-resolution-types.ts](https://github.com/hecateq/hecateq-openagent/blob/main/packages/model-core/src/model-resolution-types.ts) - [packages/model-core/src/model-requirements.ts](https://github.com/hecateq/hecateq-openagent/blob/main/packages/model-core/src/model-requirements.ts) - [packages/model-core/src/known-variants.ts](https://github.com/hecateq/hecateq-openagent/blob/main/packages/model-core/src/known-variants.ts) - [packages/model-core/src/model-capabilities/get-model-capabilities.ts](https://github.com/hecateq/hecateq-openagent/blob/main/packages/model-core/src/model-capabilities/get-model-capabilities.ts) - [packages/hashline-core/package.json](https://github.com/hecateq/hecateq-openagent/blob/main/packages/hashline-core/package.json) - [packages/web/package.json](https://github.com/hecateq/hecateq-openagent/blob/main/packages/web/package.json)
# 项目概览 ## 项目定位与背景 Hecateq OpenAgent 是一个面向 OpenCode 生态的 AI 代理编排插件，基于 `oh-my-openagent` 进行深度定制，旨在与 Hecateq 代理工作流引擎协同工作。当前首个 Beta 版本为 `v0.1.0-hecateq.1`，重点引入任务图编排、自愈式记忆管理、校验护栏等能力。仓库根目录的 [package.json](https://github.com/hecateq/hecateq-openagent/blob/main/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/*` 为基本单位划分职责清晰的功能模块。下表罗列了若干关键包及其角色定位： | 包名 | 主要职责 | 关键证据 | |------|----------|----------| | `@code-yeongyu/lsp-tools-mcp` | 通过 stdio MCP 暴露语言服务器协议工具 | [packages/lsp-tools-mcp/package.json:1-15]() | | `rules-engine` | 项目级规则发现、源优先级排序 | [packages/rules-engine/src/constants.ts:1-15]() | | `model-core` | 模型解析、能力探测、回退链与规范化 | [packages/model-core/src/index.ts:1-20]() | | `hashline-core` | 基于哈希锚点的增量编辑核心 | [packages/hashline-core/package.json:1-15]() | | `web` | 基于 Next.js 15 / React 19 的文档与控制台 | [packages/web/package.json:1-20]() | ### 架构关系图 ```mermaid 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 集成](lsp-tools-mcp.md) - [模型解析与回退链](model-resolution.md) - [规则引擎与项目规则发现](rules-engine.md) - [Hashline 锚点编辑](hashline-core.md) --- ## Lib 模块 ### 相关页面 相关主题：[项目概览](#page-overview), [Src 模块](#page-packages-model-core-src)
相关源码文件 以下源码文件用于生成本页说明： - [packages/web/lib/docs-source.ts](https://github.com/hecateq/hecateq-openagent/blob/main/packages/web/lib/docs-source.ts) - [packages/web/package.json](https://github.com/hecateq/hecateq-openagent/blob/main/packages/web/package.json) - [packages/web/scripts/generate-docs-content.mjs](https://github.com/hecateq/hecateq-openagent/blob/main/packages/web/scripts/generate-docs-content.mjs) - [packages/model-core/src/index.ts](https://github.com/hecateq/hecateq-openagent/blob/main/packages/model-core/src/index.ts) - [packages/rules-engine/src/constants.ts](https://github.com/hecateq/hecateq-openagent/blob/main/packages/rules-engine/src/constants.ts) - [packages/lsp-tools-mcp/src/lsp/language-mappings.ts](https://github.com/hecateq/hecateq-openagent/blob/main/packages/lsp-tools-mcp/src/lsp/language-mappings.ts)
# Lib 模块 ## 概述 `Lib 模块` 位于 [`packages/web/lib/`](https://github.com/hecateq/hecateq-openagent/tree/main/packages/web/lib) 目录，是 Hecateq OpenAgent 文档站点的核心工具层。它位于 Next.js 15 页面路由与底层数据源之间，为文档渲染、统计聚合、章节划分以及通用工具函数提供共享能力。该模块的设计哲学是“服务端生成 + 客户端轻引用”，即文档内容在构建阶段通过脚本生成，运行期只需按需加载。 资料来源：[packages/web/package.json:1-50](https://github.com/hecateq/hecateq-openagent/blob/main/packages/web/package.json) ## 文件结构与职责 下表总结了 `packages/web/lib/` 下常见文件及其职责（基于仓库源码与 `package.json` 中的脚本入口推断）： | 文件 | 职责 | 直接证据 | |------|------|----------| | `docs-source.ts` | 从构建期生成的映射中按文件名读取 Markdown 原文 | `loadDocSource` 函数 | | `docs-sections.ts` | 按章节对文档进行分组，供导航与目录使用 | 文档站点的导航组件引用 | | `stats.ts` | 聚合仓库统计指标（提交数、贡献者数等） | 站点首页指标卡引用 | | `utils.ts` | 通用工具函数（如类名合并、字符串归一化） | 多页面共享样式类逻辑 | 资料来源：[packages/web/lib/docs-source.ts:1-7](https://github.com/hecateq/hecateq-openagent/blob/main/packages/web/lib/docs-source.ts) ## 文档加载机制 `docs-source.ts` 是文档站点与底层内容之间的桥梁。其实现仅有 8 行： ```typescript 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](https://github.com/hecateq/hecateq-openagent/blob/main/packages/web/lib/docs-source.ts)；[packages/web/package.json:24](https://github.com/hecateq/hecateq-openagent/blob/main/packages/web/package.json) ## 与其他模块的协同 `Lib 模块` 并非孤岛，它与上层页面以及同仓库的若干核心包共同组成文档生态： ```mermaid flowchart LR A[Markdown 源文件] --> B[scripts/generate-docs-content.mjs] B --> C[docs-content.generated.ts] C --> D[lib/docs-source.ts
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`](https://github.com/hecateq/hecateq-openagent/blob/main/packages/web/package.json) 中作为依赖引入）解析为 HTML。 - **导航分组**：`docs-sections.ts` 负责把多份文档组织成章节，驱动侧边栏。 - **统计信息**：`stats.ts` 与 `utils.ts` 提供首页指标卡所需的数据与样式辅助函数。 资料来源：[packages/web/package.json:14-43](https://github.com/hecateq/hecateq-openagent/blob/main/packages/web/package.json) ## 边界与扩展注意 虽然 `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`](https://github.com/hecateq/hecateq-openagent/blob/main/packages/rules-engine/src/constants.ts) 定义 `PROJECT_MARKERS`、`EXCLUDED_DIRS` 等枚举，web 端如需复用规则相关常量，应通过包间依赖导入而非复制粘贴。 资料来源：[packages/rules-engine/src/constants.ts:1-20](https://github.com/hecateq/hecateq-openagent/blob/main/packages/rules-engine/src/constants.ts)；[packages/model-core/src/index.ts:1-50](https://github.com/hecateq/hecateq-openagent/blob/main/packages/model-core/src/index.ts) ## 常见错误与排查 | 症状 | 可能根因 | 排查建议 | |------|----------|----------| | `Unknown doc file: xxx` | 文件未被 `generate-docs-content.mjs` 收录 | 检查脚本配置，重新生成 `docs-content.generated.ts` | | 类型错误 `Property 'X' does not exist` | 修改了 `DOC_SOURCES` 类型但未重新运行生成脚本 | 执行 `bun run type-check` 触发脚本 | | 章节缺失 | `docs-sections.ts` 未覆盖新文档 | 在该文件中追加章节映射 | | 样式错乱 | `utils.ts` 的类名合并函数未处理 Tailwind 冲突 | 确认使用 `tailwind-merge` 而非简单拼接 | 资料来源：[packages/web/lib/docs-source.ts:1-8](https://github.com/hecateq/hecateq-openagent/blob/main/packages/web/lib/docs-source.ts) ## See Also - [LSP Tools MCP 包](../packages/lsp-tools-mcp/README.md) - [Model Core 解析器](../packages/model-core/src/model-resolver.ts) - [Rules Engine 常量](../packages/rules-engine/src/constants.ts) - [Hecateq OpenAgent 主页](../README.md) --- ## Src 模块 ### 相关页面 相关主题：[Lib 模块](#page-packages-web-lib), [Src 模块](#page-packages-lsp-tools-mcp-src)
相关源码文件 以下源码文件用于生成本页说明： - [packages/model-core/src/index.ts](https://github.com/hecateq/hecateq-openagent/blob/main/packages/model-core/src/index.ts) - [packages/model-core/src/model-requirements.ts](https://github.com/hecateq/hecateq-openagent/blob/main/packages/model-core/src/model-requirements.ts) - [packages/model-core/src/fallback-chain-from-models.ts](https://github.com/hecateq/hecateq-openagent/blob/main/packages/model-core/src/fallback-chain-from-models.ts) - [packages/model-core/src/known-variants.ts](https://github.com/hecateq/hecateq-openagent/blob/main/packages/model-core/src/known-variants.ts) - [packages/model-core/src/model-resolution-types.ts](https://github.com/hecateq/hecateq-openagent/blob/main/packages/model-core/src/model-resolution-types.ts) - [packages/model-core/src/model-capabilities/get-model-capabilities.ts](https://github.com/hecateq/hecateq-openagent/blob/main/packages/model-core/src/model-capabilities/get-model-capabilities.ts) - [packages/lsp-tools-mcp/src/lsp/language-mappings.ts](https://github.com/hecateq/hecateq-openagent/blob/main/packages/lsp-tools-mcp/src/lsp/language-mappings.ts) - [packages/lsp-tools-mcp/src/lsp/types.ts](https://github.com/hecateq/hecateq-openagent/blob/main/packages/lsp-tools-mcp/src/lsp/types.ts) - [packages/rules-engine/src/constants.ts](https://github.com/hecateq/hecateq-openagent/blob/main/packages/rules-engine/src/constants.ts) - [packages/hashline-core/package.json](https://github.com/hecateq/hecateq-openagent/blob/main/packages/hashline-core/package.json) - [packages/web/lib/docs-source.ts](https://github.com/hecateq/hecateq-openagent/blob/main/packages/web/lib/docs-source.ts)
# Src 模块 `Src 模块` 是 Hecateq OpenAgent 多包仓库中各功能包内部的源代码根目录集合。仓库采用 monorepo 结构,每个子包(如 `model-core`、`lsp-tools-mcp`、`rules-engine`、`hashline-core` 等)的实现代码统一放在其自身的 `src/` 子目录下,负责核心业务逻辑、模型解析、LSP 协议桥接、规则发现以及文档加载等不同职责。本页基于仓库中可读的源码文件,对主要 `src` 模块的功能边界、关键导出与典型用法进行梳理。 ## 模块总览 下表汇总了本次审查范围内各 `src` 模块的核心定位(表格内容均直接来源于对应的 `package.json` 与源码导出): | 包名 | `src` 目录职责 | 关键证据 | |------|----------------|----------| | `@hecateq/model-core` | 模型能力解析、回退链构建、规范化、消毒、能力快照 | 资料来源:[packages/model-core/src/index.ts:1-50]() | | `@code-yeongyu/lsp-tools-mcp` | 通过 stdio MCP 暴露 LSP 工具,含语言映射与类型 | 资料来源:[packages/lsp-tools-mcp/package.json:1-40]() | | `@hecateq/rules-engine` | 项目规则源发现、优先级排序、目录排除 | 资料来源:[packages/rules-engine/src/constants.ts:1-30]() | | `@oh-my-opencode/hashline-core` | 基于哈希锚点的文本编辑核心逻辑 | 资料来源:[packages/hashline-core/package.json:1-15]() | | `packages/web` | 通过 `lib/docs-source.ts` 加载生成式文档源 | 资料来源:[packages/web/lib/docs-source.ts:1-7]() | ## 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]()。 ```mermaid 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](lsp-tools-mcp.md) - [Rules Engine](rules-engine.md) - [Hashline Core](hashline-core.md) - [Model Core 解析管线](model-core-resolver.md) --- ## Src 模块 ### 相关页面 相关主题：[Src 模块](#page-packages-model-core-src)
相关源码文件 以下源码文件用于生成本页说明： - [packages/lsp-tools-mcp/src/lsp/language-mappings.ts](https://github.com/hecateq/hecateq-openagent/blob/main/packages/lsp-tools-mcp/src/lsp/language-mappings.ts) - [packages/lsp-tools-mcp/src/lsp/types.ts](https://github.com/hecateq/hecateq-openagent/blob/main/packages/lsp-tools-mcp/src/lsp/types.ts) - [packages/lsp-tools-mcp/README.md](https://github.com/hecateq/hecateq-openagent/blob/main/packages/lsp-tools-mcp/README.md) - [packages/lsp-tools-mcp/package.json](https://github.com/hecateq/hecateq-openagent/blob/main/packages/lsp-tools-mcp/package.json) - [packages/rules-engine/src/constants.ts](https://github.com/hecateq/hecateq-openagent/blob/main/packages/rules-engine/src/constants.ts) - [packages/model-core/src/index.ts](https://github.com/hecateq/hecateq-openagent/blob/main/packages/model-core/src/index.ts) - [packages/model-core/src/model-resolution-types.ts](https://github.com/hecateq/hecateq-openagent/blob/main/packages/model-core/src/model-resolution-types.ts) - [packages/model-core/src/known-variants.ts](https://github.com/hecateq/hecateq-openagent/blob/main/packages/model-core/src/known-variants.ts) - [packages/model-core/src/fallback-chain-from-models.ts](https://github.com/hecateq/hecateq-openagent/blob/main/packages/model-core/src/fallback-chain-from-models.ts) - [packages/model-core/src/model-requirements.ts](https://github.com/hecateq/hecateq-openagent/blob/main/packages/model-core/src/model-requirements.ts) - [packages/model-core/src/model-capabilities/get-model-capabilities.ts](https://github.com/hecateq/hecateq-openagent/blob/main/packages/model-core/src/model-capabilities/get-model-capabilities.ts) - [packages/hashline-core/package.json](https://github.com/hecateq/hecateq-openagent/blob/main/packages/hashline-core/package.json) - [packages/web/package.json](https://github.com/hecateq/hecateq-openagent/blob/main/packages/web/package.json) - [packages/web/lib/docs-source.ts](https://github.com/hecateq/hecateq-openagent/blob/main/packages/web/lib/docs-source.ts)
# Src 模块 ## 概述 `hecateq-openagent` 是一个面向 OpenCode 的多包 monorepo，其 `src` 代码按职责拆分为多个内部 package。每个子包都遵循 TypeScript ESM 规范，并通过 `packages/*/src` 目录组织模块化源码。整体结构可以划分为四大子域：语言服务协议工具（`lsp-tools-mcp`）、模型解析与能力协商（`model-core`）、规则加载与优先级（`rules-engine`）、文档与 Web 呈现（`web`、`hashline-core`）。这些子包共同支撑 Hecateq 工作流引擎中的任务编排、记忆管理与验证机制。资料来源：[packages/lsp-tools-mcp/README.md](https://github.com/hecateq/hecateq-openagent/blob/main/packages/lsp-tools-mcp/README.md)、[packages/model-core/src/index.ts](https://github.com/hecateq/hecateq-openagent/blob/main/packages/model-core/src/index.ts) ## 主要子模块 ### LSP 工具模块（lsp-tools-mcp） 该模块作为 stdio MCP 服务器独立暴露语言服务协议工具，是 `codex-lsp` 和 `oh-my-openagent` 两个下游插件的"上游真实源"（通过 git submodule 引用）。它对所有代理注册的 MCP 工具包括 `lsp_diagnostics`、`lsp_goto_definition`、`lsp_find_references`、`lsp_symbols`、`lsp_prepare_rename`、`lsp_rename` 与 `lsp_status`。资料来源：[packages/lsp-tools-mcp/README.md](https://github.com/hecateq/hecateq-openagent/blob/main/packages/lsp-tools-mcp/README.md) 模块内部通过文件扩展名映射到 LSP 语言 ID（`language-mappings.ts`），并以严格类型描述 LSP 数据结构。`types.ts` 中定义了 `Range`、`Diagnostic`、`TextEdit`、`WorkspaceEdit`、`PrepareRenameResult` 等核心协议类型，配套的 `SeverityFilter` 联合类型限定为 `"error" | "warning" | "information" | "hint" | "all"`。资料来源：[packages/lsp-tools-mcp/src/lsp/types.ts](https://github.com/hecateq/hecateq-openagent/blob/main/packages/lsp-tools-mcp/src/lsp/types.ts)、[packages/lsp-tools-mcp/src/lsp/language-mappings.ts](https://github.com/hecateq/hecateq-openagent/blob/main/packages/lsp-tools-mcp/src/lsp/language-mappings.ts) 包入口为 `@code-yeongyu/lsp-tools-mcp`，`bin` 字段指向 `./dist/cli.js`，通过 `tsc -p tsconfig.build.json` 构建，使用 `vitest` 进行测试、`biome` 进行代码检查。资料来源：[packages/lsp-tools-mcp/package.json](https://github.com/hecateq/hecateq-openagent/blob/main/packages/lsp-tools-mcp/package.json) ### 模型核心模块（model-core） `model-core` 负责统一的模型解析、能力协商与回退链构建。`index.ts` 暴露的公共 API 包括 `resolveModel`、`resolveModelWithFallback`、`normalizeFallbackModels`、`flattenToFallbackModelStrings` 等函数，以及 `fuzzyMatchModel`、`isModelAvailable`、`transformModelForProvider` 等工具。资料来源：[packages/model-core/src/index.ts](https://github.com/hecateq/hecateq-openagent/blob/main/packages/model-core/src/index.ts) | 文件 | 职责 | |------|------| | `model-resolution-types.ts` | 定义 `DelegatedModelConfig`、`ModelResolutionRequest`、`ModelResolutionResult` 等类型 | | `model-requirements.ts` | 维护 `AGENT_MODEL_REQUIREMENTS`、`CATEGORY_MODEL_REQUIREMENTS` 与回退链 | | `fallback-chain-from-models.ts` | 解析带括号或后缀的模型字符串，提取 `variant` | | `known-variants.ts` | 枚举 `low/medium/high/xhigh/max/minimal/none/auto/thinking` 等已知变体 | | `model-capabilities/get-model-capabilities.ts` | 按 `runtime > override > snapshot > heuristic` 顺序合并能力诊断 | 资料来源：[packages/model-core/src/model-resolution-types.ts](https://github.com/hecateq/hecateq-openagent/blob/main/packages/model-core/src/model-resolution-types.ts)、[packages/model-core/src/known-variants.ts](https://github.com/hecateq/hecateq-openagent/blob/main/packages/model-core/src/known-variants.ts)、[packages/model-core/src/fallback-chain-from-models.ts](https://github.com/hecateq/hecateq-openagent/blob/main/packages/model-core/src/fallback-chain-from-models.ts) 能力解析函数在每个维度上记录来源（`runtime`/`override`/`snapshot`/`heuristic`/`none`），并通过 `ModelCapabilitiesDiagnostics` 返回 `reasoningEfforts`、`supportsTemperature`、`supportsTopP`、`maxOutputTokens` 等字段的来源信息，便于上层做可观测的回退决策。资料来源：[packages/model-core/src/model-capabilities/get-model-capabilities.ts](https://github.com/hecateq/hecateq-openagent/blob/main/packages/model-core/src/model-capabilities/get-model-capabilities.ts) ### 规则引擎模块（rules-engine） `rules-engine` 的 `constants.ts` 集中声明项目识别与规则源优先级。`PROJECT_MARKERS`（`.git`、`pyproject.toml`、`package.json`、`Cargo.toml`、`go.mod`、`.venv`）用于判断是否进入项目根；`EXCLUDED_DIRS` 排除 `node_modules`、`.git`、`dist`、`build`、`.turbo`、`.next`、`coverage` 等噪声目录。资料来源：[packages/rules-engine/src/constants.ts](https://github.com/hecateq/hecateq-openagent/blob/main/packages/rules-engine/src/constants.ts) `SOURCE_PRIORITY` 是一张 `ReadonlyMap`，把项目级规则（`.omo/rules=0`、`.claude/rules=1`、`.cursor/rules=2`、`.github/instructions=3`、`.github/copilot-instructions.md=4`、`.sisyphus/rules=5`）排在用户级规则（`~/.omo/rules=100`、…）之前，数值越小优先级越高，从而保证团队级规则覆盖个人规则。资料来源：[packages/rules-engine/src/constants.ts](https://github.com/hecateq/hecateq-openagent/blob/main/packages/rules-engine/src/constants.ts) ### 文档与哈希锚模块（web、hashline-core） `web` 子包基于 Next.js 15.5 + React 19 构建，使用 `next-intl` 进行国际化、`marked` 渲染 Markdown、`tailwindcss` 提供样式，并通过 `opennextjs-cloudflare` 部署到 Cloudflare。`lib/docs-source.ts` 调用 `loadDocSource(file)` 从生成常量 `DOC_SOURCES` 中按文件名取回 Markdown 文本。资料来源：[packages/web/package.json](https://github.com/hecateq/hecateq-openagent/blob/main/packages/web/package.json)、[packages/web/lib/docs-source.ts](https://github.com/hecateq/hecateq-openagent/blob/main/packages/web/lib/docs-source.ts) `hashline-core` 是私有子包（`@oh-my-opencode/hashline-core`），仅暴露 `src/index.ts`，依赖 `diff@^9.0.0`，为"哈希锚点"编辑提供纯 TypeScript 核心逻辑，被上层工具用于在编辑大文件时定位稳定的行级锚点。资料来源：[packages/hashline-core/package.json](https://github.com/hecateq/hecateq-openagent/blob/main/packages/hashline-core/package.json) ## 模块间关系 ```mermaid flowchart LR Web[packages/web
Next.js 文档站] --> Docs[lib/docs-source.ts] Agent[OpenCode 代理运行时] --> LSP[lsp-tools-mcp
stdio MCP] Agent --> Model[model-core
resolveModel / 能力] Agent --> Rules[rules-engine
规则优先级] Model --> Provider[(Provider
anthropic / openai / vercel)] LSP --> LSPServer[(LSP Server
typescript / pyright / …)] Rules --> FS[(项目 / 用户文件系统)] ``` 资料来源：[packages/lsp-tools-mcp/README.md](https://github.com/hecateq/hecateq-openagent/blob/main/packages/lsp-tools-mcp/README.md)、[packages/model-core/src/index.ts](https://github.com/hecateq/hecateq-openagent/blob/main/packages/model-core/src/index.ts)、[packages/rules-engine/src/constants.ts](https://github.com/hecateq/hecateq-openagent/blob/main/packages/rules-engine/src/constants.ts) ## 关键设计模式 - **上游真实源（Upstream of Truth）**：`lsp-tools-mcp` 强调"修改必须落到本仓库，下游通过 bump submodule pointer 同步"，避免在下游重复实现同一 LSP 运行时。资料来源：[packages/lsp-tools-mcp/README.md](https://github.com/hecateq/hecateq-openagent/blob/main/packages/lsp-tools-mcp/README.md) - **能力诊断四元来源**：模型能力字段在 `runtime > override > snapshot > heuristic` 链路上回退，并通过 `CapabilitiesDiagnostics` 标注来源，便于排错。资料来源：[packages/model-core/src/model-capabilities/get-model-capabilities.ts](https://github.com/hecateq/hecateq-openagent/blob/main/packages/model-core/src/model-capabilities/get-model-capabilities.ts) - **解析后端宽容性**：`parseFallbackModelEntry` 同时识别括号变体 `model(high)` 与空格后缀 `model high`，并通过 `KNOWN_VARIANTS` 白名单过滤，避免误判版本号中的 `5.0` 等。资料来源：[packages/model-core/src/fallback-chain-from-models.ts](https://github.com/hecateq/hecateq-openagent/blob/main/packages/model-core/src/fallback-chain-from-models.ts) - **规则源优先级数字越小越优先**：项目级 0–5 始终胜过用户级 100+，便于团队一致性与个人配置的协调。资料来源：[packages/rules-engine/src/constants.ts](https://github.com/hecateq/hecateq-openagent/blob/main/packages/rules-engine/src/constants.ts) ## See Also - 模型回退链与已知变体：参见 `model-requirements.ts` 与 `known-variants.ts`。 - LSP 协议类型：参见 `lsp-tools-mcp/src/lsp/types.ts`。 - 项目标记与规则源优先级：参见 `rules-engine/src/constants.ts`。 - Web 文档加载：参见 `web/lib/docs-source.ts`。 - 哈希锚点编辑：参见 `hashline-core/src/index.ts`（通过 `package.json` 导出）。 --- --- ## Doramagic 踩坑日志 项目：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