epiagentkit-maintenance

# EpiAgentKit 维护 把规则、skills、hooks、脚本、测试和文档视为一个行为系统。基于真实缺口持续优化，不做追加式堆砌，不以缩短文件为由丢失已有能力。 每次 skill 变更都自动执行本流程，用户无需重复声明；同时使用 `skill-creator`。先保护完整工作流，再满足本次新增或修复需求。 ## 1. 建立基线 1. 确认目标是 EpiAgentKit 源仓库或用户明确指定的副本；不要把普通研究项目当成本仓库维护。 2. 确认根 `CLAUDE.md`、`AGENTS.md` 已读取且未变化；阅读目标组件，并列出目标 skill 目录。按改动涉及的分支读取适用 references、直接调用者和测试；只有改变共享规则、分流、依赖或安装行为时才检查相关同步路径。局部文字修改不要求读取全部引用、脚本和整个仓库；出现跨组件影响的证据时再扩大。 3. 只读检查运行环境。先判断命令是否存在，再运行验证；缺少 R、Python、Node、Java、LibreOffice、TeX、Git 或依赖时说明影响和用户可执行的准备方式，不创建环境，也不安装、升级或降级任何工具。 4. 按全局 Git 规则建立基线：可用且当前目录为仓库时读取状态和差异；否则改用文件清单、内容检索和直接校验，不把缺少 Git 判为任务失败。 5. 不读取后回显凭证、私密设置或环境变量完整内容；只报告键、类型和设置状态。 6. 按根 `AGENTS.md` 的 workbench 约定建立维护批次并先写 `PLAN.md`。只有新建 skill，或用户当轮明确要求审阅成果时，才建立 `review/`；修改、修复、重命名或删除既有 skill 时不自动生成。结束后保留 `FINDINGS.md`、实际生成的 `review/` 与需要追溯的试验依据，并按仓库规则清理可重建的 runtime。 7. Windows 维护遵循全局与根 `AGENTS.md` 的 shell、编码和命令安全规则；临时多行逻辑放在本批次 workbench，长期工具放在职责匹配的 `scripts/`。 ## 2. 记录变更依据 编辑前明确记录： - **观察到的缺口**：真实失败、重复、冲突、误触发、漏触发、不可执行规则或过高上下文成本。 - **必须保留的行为**：旧场景、输出、兼容性、安全边界和安装结果。 - **最小变更集**：哪些内容保留、重写、合并、移到 reference 或脚本、删除或新增，以及理由。 - **代表性验证**：至少一个旧场景和一个新场景；涉及边界时同时包含应触发与不应触发用例。 - **同类问题边界**：把用户点名的词、文件或项目当作代表实例，说明共同原因、受影响范围与合法例外；扫描所有受影响的 rules、skills、references、脚本、模板、测试和文档，不停在字面替换或单个文件。 没有可复现缺口时，不新增规则。两个方案通过相同验证时，选择更短、唯一来源更清楚、维护成本更低的一项。 ### 接收其它项目的 `workflow.txt` `workflow.txt` 是现场问题的交接材料，不是完整工作流，也不能直接决定修改位置。用户引用该文件要求调整 EpiAgentKit 时： 1. 完整读取报告并先检查它能否脱离原会话独立理解。每项记录必须能确定工作项、对象、触发条件、执行动作、证据、完成标准、不适用范围和合法例外；指代或边界不清时标为待核验，不替报告作者补全含义。 2. 分别提取用户已经确认的目标、可定位的实际产物、报告中的原因推断、候选调整和尚缺证据。报告所在项目看不到完整规则或当时版本不明时，不把它的推断写成已确认事实。 3. 在当前仓库核对报告涉及的根规则、skills、references、模板、脚本、hooks、同步器、测试和文档；Git 历史可用且确有助于还原当时规则时再查看相应版本。无法访问报告引用的原产物时，明确降低结论置信度。 4. 按最早失效环节合并同源问题，再决定最小有效实现。根 `CLAUDE.md`、skill、reference、脚本、hook、同步器、测试和 README 都可以修改；不因报告建议某个文件就照抄，也不预先排除能够可靠实现目标的组件。 5. 对每项候选调整确认用户目标是否普遍适用、哪些旧行为和合法例外必须保留，以及怎样用旧场景和新场景验证。现有规则已经足够时，优先修正实际调用、制作或验收步骤，不追加同义提醒。 6. 报告证据不足且当前体系也无法复现缺口时，不猜原因、不为求回应强行修改；说明已经核对的范围、不能采纳的建议及仍需的证据。边界不清且不同解释会改变实现时，停下请用户确认。 ### 用户纠正与真实失败的原因查找和修正 用户指出未遵循规范、用词不清、产物不完整或完成状态失真时，必须先查明原有流程为什么没有阻止问题，再编辑： 1. 对照用户要求、实际产物和当时适用的规则，记录可定位证据，不以道歉、重新承诺或字面替换代替原因判断。 2. 判断最早出现问题的规则或步骤：规则缺失、任务分流错误、适用 reference 未被设为必读、制作过程未执行、验收未运行、完成状态误报、工作流自身用词不清，或工具无法可靠执行。 3. 修改最早且可复用的规则或步骤。已有规则但被跳过时，不再追加同义提醒；把要求直接写进适用 skill 的实际制作步骤、完成条件或能够可靠判断的脚本检查。 4. 扫描所有受同一原因影响的工作流和合法例外，分别决定保留或改写。用户点名的项目只作为回归样例，不把项目事实写进通用 skill。 5. 用真实旧场景和新失败场景复核。只有新场景被阻止、旧场景仍成立且完成状态不再夸大时，才认为原因已经处理。 用户已经确认且适用于后续同类任务的要求，必须固化到最早且唯一的可执行位置，并用代表性回归测试保护；不得只写进当轮说明、临时提示词或审阅文档，迫使用户在以后重复要求。项目专属事实、私密材料和只适用于单次产物的选择仍留在项目或 workbench，不提升为通用规则。 向用户更新进度时先说明已经定位的工作流原因、正在修改的规则或步骤和仍需核验的证据；不能只回复态度或重复用户要求。 ## 3. 确定唯一维护位置 | 内容 | 维护位置 | | --- | --- | | 每个会话都必须知道的跨任务安全要求、任务总分流、唯一来源说明、完成条件 | 根 `CLAUDE.md` | | 本仓库结构、编码、验证、贡献和维护约定 | 根 `AGENTS.md` | | 任务触发边界与核心工作流 | 对应 `SKILL.md` | | 条件细节、长规范、变体和示例 | 对应 `references/` | | 重复且需要确定性的操作 | 对应 `scripts/` | | 必须在固定生命周期执行或阻断的检查 | `hooks/` 与客户端配置 | | 安装、同步、需要同步的文件清单和双端对应关系 | `scripts/config_core.py`、同步器及工作流检查 | | 面向使用者的能力、安装与安全说明 | `README.md` | 每项规则只在一处维护。更新该处时，同步修改所有调用者、模板、测试和文档；删除被替代的旧表述。不要把 skill 的条件参数复制进全局 `CLAUDE.md`，也不要把全局优先级在各 skill 重写一遍。 修改跨客户端元数据、规则加载、工具适配或 hooks 时，读取 [平台兼容性](references/platform-compatibility.md)，并按当前官方资料与实际环境核验。领域流程不写死客户端专有工具名；确需工具时在对应分支说明可用条件与缺失处理。 ## 4. 按组件修改 ### CLAUDE.md 与 AGENTS.md - 先核对 Claude Code 官方 [memory](https://code.claude.com/docs/en/memory) 与 [best practices](https://code.claude.com/docs/en/best-practices)；只写入当前任务需要且经核验的规则。 - 根 `CLAUDE.md` 目标不超过 200 行，使用短段落、标题、列表和可验证措辞。只保留广泛适用且删除后会造成错误的规则；领域流程转 skill，目录或语言专属规则转项目或路径级规则。 - `AGENTS.md` 只保留本仓库开发约定，不复制领域规则。Claude Code 与 Codex 需要同一行为时，从仓库唯一来源同步，不手工维护两份不同正文。 - “简洁、优雅、规范”必须落到可检查标准：目的适配、事实准确、层级清楚、结构紧凑、术语一致、版式克制、命令可执行、验收明确。 ### Skills 与 references - description 简短说明能力和触发场景，只保留能防止相邻任务误触发的排除边界；前后调用顺序、工具选择与验收步骤放入正文。不要以框架清单、任务百科或通用优点吸引无关请求；核心步骤用祈使式。 - `SKILL.md` 只保留选择和执行步骤，条件细节放在可以从中直接找到的 references。避免多层引用、重复说明、教程式铺陈和未被任何流程使用的资源。 - 审查或修改 skill 时，用自然领域语言核对每个任务分支的触发、排除、唯一输入、专业动作、需要时配合的 skill、最少检查、扩大检查条件和完成证据。每项检查必须指出本次修改可能造成的具体错误；局部纠正不使未受影响的项目或发布检查失效。内容 skill 负责专业含义，文件 skill 负责文件结构和显示，不重复证明同一事项。 - 对每项拟新增、保留或重写的要求做必要性判定：先假设用户当轮指示、根规则、已调用的内容与文件 skill、适用模板以及可靠的工具或格式默认均已生效，再问删除该要求是否会改变动作、决策、例外、停止条件或验收结果。只有增加至少一种独立行为时才保留；若删除后行为不变，直接删除，不把已经自然成立的结果或“没有发生某个错误”改写为新的正面要求。 - 一个 skill 中验证有效的提示词经验可作为其它 skill 的候选方法，但必须先核对目标任务、工具能力、输入结构、失败模式和验收责任是否相同，并用该 skill 的代表性任务验证收益。只迁移确有帮助的原则，不机械复制五段标题、字段、字数、禁止项或完整模板；不适用时保留原流程。多个 skill 共同调用同一内容 skill 时，由内容 skill 完成其专业步骤，调用者继续负责自己的成品位置、格式和交付验收。 - 新 skill 必须使用 `skills/skill-creator/scripts/init_skill.py` 初始化；删除全部占位资源，仅保留实际需要的文件。 - 运行 `python skills/skill-creator/scripts/quick_validate.py skills/<skill-name>`，再检查引用存在、触发边界、旧场景与新场景。 ### 新建 Skill 与按需成果审阅 新建一个 skill 时，必须在提交前形成至少两份可独立打开、分别验收的真实成果。修改、修复、重命名或删除既有 skill 时，默认使用代表性实跑和回归测试验收；只有用户当轮明确要求时才生成审阅成果。 新建 skill 或用户要求成果审阅时，制作前完整读取 [成果审阅要求](references/review-artifacts.md)，执行真实成果、`review/INDEX.md` 和提交前确认要求。成果审阅只属于新建 skill 或用户明确要求的维护任务，不改变目标技能的日常产物数量。只有用户明确确认当前成果无误并同意提交，才提交该成果对应的新建或受审阅变更；已明确覆盖当前成果与提交的授权无需重复询问。 ### Hooks、脚本与同步器 - 需要确定性阻断时用 hook，不用提示词模拟强制执行；同时控制误报、漏报、重复输出和上下文噪声。 - Python 运行 `python -m py_compile` 并以代表性输入实跑；Shell 运行 `bash -n` 并做安全样例；R 多行代码写入文件后用 `Rscript 文件.R` 实跑。 - Hook 变更同时核对 Claude Code 与 Codex 的事件名、匹配器、启动器、冲突清理和安装清单。Windows 路径与编码必须有代表性验证。 - 安装器、同步器、依赖闭包或工作流规则变更后，运行 `python scripts/audit_workflow_contracts.py`；不得只凭退出码，必须扫描完整输出中的异常词。 ## 5. 验证与完成确认 验证采用最低充分层级，不为防御性完整而自动升级： 1. 每次修改均运行目标组件的语法、validator、引用检查和能覆盖行为变化的代表性实跑。 2. 运行直接覆盖受影响组件或合同的测试模块。只有修改根规则、任务分流、共享依赖、hooks、安装/同步器、跨多个 skill 的共同合同，或聚焦测试无法覆盖影响面时，才运行完整 `python -m unittest discover -s scripts/tests -v`。 3. 只有修改安装器、同步器、依赖闭包、跨客户端文件清单、根工作流规则或共享分流合同时，才运行 `python scripts/audit_workflow_contracts.py`；孤立 skill 的正文、reference 或局部脚本变更不因此自动运行双平台安装审计。 4. 扫描本轮实际验证输出中的 `error|warning|traceback|failed|nan` 并逐项归因；不额外运行无关命令来制造扫描对象，也不能把预期提示、库噪声或真实失败混为一类。 5. 在受影响范围内检查占位文件、失效引用、重复维护位置、生成过程痕迹和来源不明的既有改动。中文修改按全局中文终审要求逐句检查目标读者、主体、动作、依据、条件和确认责任；词面扫描只用于发现高确定性线索，不能代替语境审查。 适用检查通过后进入交付；只有新改动、新失败或明确未覆盖的影响才扩大或重跑。提示词、模型或技能分流调整同时比较旧新代表任务的实际选择、完成范围与确认次数；字符量只证明加载量变化，静态关键词和依赖检查不证明模型行为或耗时改善。共享规则继续兼容 Claude Code 与 Codex，不在领域 skill 中写死模型、推理强度或 API 参数。 Git 可用且当前目录为仓库时，最后审查完整差异。新建 skill 或用户当轮明确要求成果审阅时，先完成审阅并等待用户明确同意当前版本，未获同意时保持未提交；其余提交、push、提交后同步和 doctor 按根 `CLAUDE.md` 与 `AGENTS.md` 执行。Git 不可用或当前目录不是仓库时报告“Git 已跳过”，并在完成前按仓库规则运行同步和 doctor。 ## 6. 交付说明 先报告完成结果，再列出：改动的行为、保留的旧行为、验证命令与结果、兼容性影响及必要时怎样恢复、Git 已提交或已跳过；本轮启用成果审阅时再列出成果及覆盖范围和等待确认状态。不要把探索过程、内部思维或冗长逐文件流水账写进交付。