indesign-cli AGENTS.md

AGENTS 主入口

0. 设计原则

• 先理解现状，再动手。 先读代码、工具定义、测试和当前文档，避免凭旧印象改项目。
• 收口优先。 能复用现有 core、tools、utils 时，不新增平行实现。
• CLI 复用现有能力。 CLI 是面向 Agent 的按需入口，不重写一套 InDesign 自动化。
• HTML 转 InDesign 在外部插件仓库实现。 本仓库只维护 indesign-cli 宿主、插件协议和 InDesign 执行底座。
• 不要把 internal 工具当死代码。 终态代码以空 profiles 表示 internal，并投影为 CLI source: hidden_handler；先查 registry、artifact、CLI 工具目录、测试和文档后再决定是否公开或删除。
• 文档按用途归档。 长期规范、方案、计划、排查、复盘分开放，避免一个目录堆成垃圾场。
• 历史资料只追溯。 当前开发以代码、AGENTS.md 和当前文档为准。

0.1 架构治理原则

• SSOT（Single Source of Truth）：工具名、schema、handler 映射、CLI 展示 id、文档目录入口必须尽量只有一个权威来源；新增第二份映射前必须说明同步机制。
• SRP（Single Responsibility Principle）：模块按职责拆分；handler 只做参数处理、脚本拼装、执行和响应包装，不承载新的业务框架。
• DRY（Don't Repeat Yourself）：重复的工具映射、响应包装、脚本执行、schema 投影应收口到共享层；但不要为了消除少量重复引入难懂抽象。
• YAGNI（You Aren't Gonna Need It）：没有当前需求、测试入口或明确计划支撑的能力不提前实现。
• KISS（Keep It Simple, Stupid）：优先选择能被当前代码、测试和文档直接解释的简单结构；复杂机制必须解决真实复杂度。

1. 真相顺序

优先级	依据	用法
1	当前用户指令	本轮任务的最高优先级
2	AGENTS.md	项目级协作入口、硬规则、目录规范
3	当前代码	校正文档、工具映射和行为判断的最终依据
4	docs/README.md 与当前 docs/	文档目录、当前说明、方案和记录
5	docs/legacy/	只追溯历史，不作为当前规范
6	Git 历史	需要恢复旧内容时才查看

冲突处理：

冲突类型	处理方式
文档与代码不一致	以代码为准，顺手修正文档
当前文档与历史文档不一致	以当前文档为准
MCP 暴露工具与 registry / artifact 不一致	以 src/tools/index.js 和 src/core/indesign-tool-registry.json 为准，先判断是否是 internal 工具
CLI 目标与 MCP 现状不一致	让 CLI 复用现有执行链路，避免重写业务能力
HTML 插件需求与 CLI 宿主不一致	先判断是否属于插件协议或 host action 边界；不要把 HTML 转换实现塞回本仓库

2. 强制规则

2.1 沟通规则

• 与用户沟通使用中文，短句，直接说结论。
• 文件名、命令、工具名、API 名保留原文，并用代码样式标出。
• 不重复解释同一件事；已确认的项目口径直接执行。

2.2 文档治理

• AGENTS.md 是唯一项目级总入口，不新增第二个总导航。
• docs/README.md 是文档目录入口，新增长期文档前先查它。
• 本项目不建立大体量项目上下文目录；当前规模直接靠 AGENTS.md、代码和专项文档维护上下文。
• 中文文档统一使用 UTF-8。
• 根目录 docs/*.md 只保留跨主题、当前仍有用的说明文档。
• 新增专题文档必须进入对应子目录，不在 docs/ 根目录随手堆文件。
• 方案设计放 docs/superpowers/specs/，实施计划放 docs/superpowers/plans/。
• 已落地并需要长期遵守的结论，沉淀到 docs/技术决策/ 或更新相关当前文档。
• 本地 Agent 任务、外部咨询、用户反馈等过程材料放 docs/AI协作/，具体分层以 docs/AI协作/README.md 为准。
• 复杂缺陷修复记录放 docs/bugfix/。
• 当前有效 review 和复盘放 docs/review/；历史材料放 docs/legacy/。