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