SkyJourneyandClaude Opus 4.7
a9a89e57c3
- decisions.md 新增 3 项：memcore-shared 共享层、lint_report 增量保活、Phase 1 锚点兜底 - feedback_plugin_dev.md 新增 2 项：skill 不重写 MCP 参数表、签名变更全量扫描 - project_overview.md：memcore 技能数 3→4，新增 memcore-shared - AUTO-FIX：feedback#skill-不重写MCP参数表 补反向引用至 decisions - 引用列：decisions/project_overview/feedback 均为 1，lint_report 为 0 - CLAUDE.md 元数据更新（commit 38beecb），引导区块刷新 Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
6.0 KiB
name, description, type, last_updated, commit
| name | description | type | last_updated | commit |
|---|---|---|---|---|
| 插件开发协作反馈 | 在此 marketplace 项目中开发插件时需遵守的协作规范和经验教训 | feedback | 2026-06-12 | 38beecb |
插件开发协作规范
新增插件时必须同步更新四个位置
规范：新增插件必须同步修改：① plugins/<name>/ 目录 ② plugins/<name>/.claude-plugin/plugin.json ③ .claude-plugin/marketplace.json 的 plugins 数组 ④ CLAUDE.md 的已发布插件表格。
Why：marketplace.json 是 Claude Code 的安装入口，CLAUDE.md 是新会话的参考文档，两者不更新会导致插件不可被发现。
How to apply：每次创建插件后用 checklist 验证四处都已修改。
cp -r 复制目录时注意目标路径存在与否
规范：用 cp -r source/ dest/ 复制 skill 目录时，若 dest/ 目录不存在，source 内容会直接成为 dest/（而非 dest/source/）。
Why：本次将 huanxi-shared 复制到 skills/ 目录时，因为 skills/ 不存在，SKILL.md 直接落在了 skills/ 下而非 skills/huanxi-shared/ 下，需要手动修复。
How to apply：多目录批量复制时，先 mkdir -p 目标目录，再逐个 cp -r；或改用第一个 cp -r 后检查结构。
引入 Skill 相对路径时需考虑运行时路径解析
规范：SKILL.md 中引用其他 skill 文件时使用 ../sibling-skill/SKILL.md 的相对路径（如 huanxi-* 系列引用 huanxi-shared），这种模式在 Claude Code 插件的 skill 目录结构下是可行的，但依赖 Claude 正确解析路径。
Why：validator 审查时指出相对路径存在解析风险，但由于 huanxi-* 系列已在用户本地以相同目录结构正常工作，打包后一致性可保持。
How to apply：若未来发现 Read 相对路径失败，改为在每个 skill 内联关键共享规则（工具签名表、缓存 TTL），降低对 Read 成功的依赖。
SKILL.md description 使用用户口语，不用内部视角
规范：frontmatter 的 description 字段应描述用户会说的话（"我有哪些模块"、"帮我写日报"），不要写内部触发条件（"当需要解析模块名/人员名为 ID 时触发"）。
Why：description 是 Claude Code 判断何时触发该技能的依据，也是展示给用户的摘要。内部视角语言对用户无意义，且不能有效触发。
How to apply：新建 skill 时，先想"用户实际会怎么说这个需求"，用这些词写 description。
plugin-validator 和 skill-reviewer 审查之后要对照实际代码修正工具签名
规范：Plugin 审查发现工具名称错误时（如 report_submit vs report_submit_item），必须回到源代码（huanxi_mcp/tools/*.py）确认实际函数签名，以代码为准修正 skill 描述。
Why：本次发现 huanxi-shared 工具索引中 report_submit/withdraw 用了旧名，leader_report_submit/withdraw 缺必填参数，weekly_report_save 参数名用 week 而非 week_number，这些都是 MCP 升级后 skill 未同步导致的。
How to apply：每次 MCP server 工具链升级后，运行 plugin-validator 对照检查 skill 中的工具调用。
skill 不要重写 MCP 参数表，引用 docstring 为单一真相
规范：MCP 工具的参数细节（字段名、必填、枚举值、类型）以后端 Python 函数 docstring 为单一真相来源。skill 文档不要重画完整字段表，最多给一个 happy path 的调用示例 + 历史踩坑说明，在 reference 文档顶部统一声明"参数细节以 MCP <tool_name> 的 docstring 为准"。
Why：本次发现 huanxi-report/references/report-draft.md 的字段表与后端 report_save_draft docstring 大幅漂移（缺 module_id 必填、progress 字段名错为 progress 应为 progress_update、虚构 status 字段），直接导致用户日报频繁报"参数缺失"。skill 一旦重画参数表，就和 MCP docstring 形成两套真相 —— 任一处改动另一处就漂移。同类漂移在 weekly（week→week_number）、task（due_date→end_date / urgent→critical / todo→not_started）、org（user_id→id）系列均出现，呈系统性问题。
How to apply：
- 写 skill 时不画字段表；如非要列字段，必须在文末加"以 MCP docstring 为准"声明
- 给 LLM 的提示是"调 MCP 时直接信任 docstring"而非"按本文档调用"
- MCP 工具签名变更时不需要改 skill（只要 skill 没硬编码参数表）
See Also：feedback_plugin_dev.md#plugin-validator 和 skill-reviewer 审查之后要对照实际代码修正工具签名 feedback_plugin_dev.md#MCP 后端工具签名变更后必须全量扫描所有 skill decisions.md#memcore-shared：路径锁定 + 全局常量的单一来源
MCP 后端工具签名变更后必须全量扫描所有 skill
规范：MCP server 的工具签名（参数名、必填项、枚举值、返回字段）变更后，必须对引用该 MCP 的所有 skill 做全量 grep 扫描，找到漂移点逐一对齐。不要依赖单元测试或调用时报错来"被动发现"。
Why：本次扫描发现 huanxi 的 6 个 skill + 7 个 reference 中漂移密度极高：4 类典型模式（字段名错 / 枚举值错 / 缺必填 / 缓存示例与后端返回结构不一致）覆盖所有 huanxi-* 系列。漂移源于后端 docstring 在多次迭代中演进，但 skill 未同步审查。这种漂移在调用时才会被发现（"参数缺失"、"字段不存在"），对用户体验是慢性损耗。
How to apply：
- 后端 PR 中涉及 MCP 工具的，PR 描述必须列出签名变更点
- 合并后立即在 marketplace 仓库做对照扫描（grep 漂移关键词，如旧字段名）
- 漂移修正与签名变更在同一 sprint 完成，不留尾巴
典型扫描点（针对 huanxi）：参数名 progress vs progress_update、due_date vs end_date、week vs week_number；枚举值 todo vs not_started、urgent vs critical；返回字段 user_id vs id。