factorio-docs-mcp: Instructions file for Codex

AGENTS.md — Factorio Docs MCP

本文件是本项目对 AI 编码助手约束与指南的唯一事实源。CLAUDE.md 仅通过 @AGENTS.md 引用本文件，禁止在两处重复维护。

项目概述

同步 Factorio 官方 mod API 文档到本地，并通过 MCP server 辅助 mod 开发与跨大版本升级迁移。能力范围：检索 + 版本对比（不做 mod 源码扫描）。

设计文档：docs/superpowers/specs/2026-07-29-factorio-docs-mcp-design.md

上下文/进度恢复（上下文丢失时必读）

当会话上下文被压缩或清空、或你对自己此前的执行状态没有记忆时，不要凭记忆猜测进度，按以下顺序恢复：

1. 读进度台账 docs/superpowers/PROGRESS.md——任务状态表、决策记录、断点都在里面（唯一事实源）。
2. 对照 git log 验证台账记载的上个提交真实存在，防止台账与实际脱节。
3. 读当前任务的计划 docs/superpowers/plans/2026-07-29-factorio-docs-mcp.md 与规格 docs/superpowers/specs/2026-07-29-factorio-docs-mcp-design.md。
4. 从台账标记的第一个未完成任务继续，绝不重复已完成任务。

每次完成一个任务，必须同步更新 PROGRESS.md 并随代码提交，保证任何时刻都能从 git 恢复断点。

架构约束（必须遵守）

• 三层边界：sync/ 只写 raw/；index/ 只读写 index.db；mcp/ 只读 index.db。数据流向单向，禁止各层的数据处理逻辑跨层耦合（如 mcp 层读取 raw 文件并解析、sync 的下载逻辑直接拼 SQL 写库）。
• 组合根例外：编排入口（sync/orchestrate.ts、cli.ts、mcp.ts）是组合根，允许为「串联三层」而调用各层的公开接口（如编排器调用 buildVersion 建索引）。但组合根只负责编排，不得在其中新增属于某一层的具体数据处理逻辑（如下载细节、SQL、解析规则）。
• 检索接口：所有检索必须经过 SearchProvider 接口，禁止在 MCP 工具内直接写 SQL。
• 数据保真：api_entries.data 列必须原样存储官方 JSON 子树，禁止裁剪字段。

已知技术债 / 重构提醒

• 编排逻辑当前寄生于 sync/orchestrate.ts：它作为组合根同时调用 sync 下载与 index 建库，功能正确但归属不纯粹。当未来编排逻辑变复杂时（如增加并发同步、断点续传、多阶段流水线、更细的失败恢复），应将其重构到中立位置（如 src/app/），使 sync/ 回归「只写 raw/」的字面纯粹。 目前按 YAGNI 暂不重构。

数据源纪律

• 仅使用官方数据源：lua-api.factorio.com（runtime/prototype JSON + archive.zip）、wube/factorio-data（含 changelog.txt）。
• 禁止引入社区/第三方数据作为 API 事实来源。
• 同步必须增量：已有版本数据只增不改；单版本失败不得影响其他版本。

语言与交互

• 与用户交互使用中文（专业名词、代码标识符除外）。
• 代码注释使用中文，遵循周边代码风格。

操作规则

• 修改任何文件之前，必须先 READ 该文件。 禁止在未读取文件的情况下直接执行 Edit 或 Write（即使全局配置已有此规则，此处重复以确保生效）。

测试要求

• 测试框架：Vitest。
• 新功能先写测试再实现（TDD）。
• L3 迁移知识的 breaking 判定规则变更时，必须同步更新召回测试 fixture。
• 运行测试：npm test；类型检查：npm run typecheck； lint：npm run lint。

工程约定

• Node.js ≥ 22（依赖内置 node:sqlite），TS 严格模式 + ESM。
• 构建：tsup（单包双 bin：fdocs / fdocs-mcp）。
• Lint/Format：Biome，提交前必须通过。
• 数据目录由 FACTORIO_DOCS_DATA 或平台用户数据目录解析，禁止硬编码路径。