Files

T

SkyJourneyandClaude Sonnet 4.6 9c2f19b579 chore: memory-sync — 新增 obsidian 插件记录 + memcore 路径锁定决策归档

- decisions.md 新增 memcore memory-update/lint 路径锁定决策条目
- project_overview.md 已发布插件表新增 obsidian 插件族（9 个技能）
- CLAUDE.md 已发布插件表同步更新，顶部元数据刷新至 9c91382
- MEMORY.md / lint_report.md 索引与执行时间更新至 2026-05-08

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

2026-05-08 11:57:01 +08:00

3.8 KiB

Raw Blame History

name, description, type, last_updated, commit

name	description	type	last_updated	commit
架构决策	Marketplace 设计中的关键技术决策及其原因	project	2026-05-08	`9c91382`

关键架构决策

plugin.json 不设 version 字段

结论：所有 plugin.json 均不含 version 字段。

Why：Claude Code 官方文档说明，若 plugin.json 设置了固定 version，推送新 commit 不改 version 字符串时，已安装用户看不到更新。省略 version 后，Claude Code 自动用 git commit SHA 做版本判断，每次推送 main 分支即为新版本。

How to apply：新增插件时不要加 version 字段。memcore 和 huanxi 均已按此规范执行。

huanxi plugin 使用 userConfig 而非环境变量传 Token

结论：plugin.json 用 userConfig + sensitive: true 声明 Bearer Token 输入，mcpServers.headers 中用 ${user_config.token} 引用。

Why：sensitive: true 将 token 存入系统钥匙链（或 ~/.claude/.credentials.json），不会出现在 settings.json 中，避免随仓库提交泄露。Claude Code 安装插件时自动弹窗提示用户输入，体验好于环境变量。

How to apply：其他需要用户配置 API Key/Token 的插件，均应使用此模式，不要用 ${ENV_VAR} 方式。

"userConfig": {
  "token": {
    "type": "string",
    "title": "寰汐 Personal Token",
    "description": "在寰汐系统后台生成，hxp_ 前缀",
    "sensitive": true
  }
}

See Also：project_overview.md#已发布插件

huanxi MCP Server 认证：Bearer Token 直连，不改后端

结论：plugin.json 配置 Authorization: Bearer ${user_config.token} header，MCP server 已有的 _PersonalTokenVerifier 直接验证 hxp_ token，无需改后端。

Why：后端已有 ASGI 中间件模式（AdminMcpAuthMiddleware）和 PersonalTokenVerifier，Bearer Token 天然支持。OAuth2 Discovery Flow 是 FastMCP 框架层的特性，当客户端直接在 header 中传 Bearer Token 时可绕过 OAuth 流程。改后端风险高且无必要。

How to apply：未来新增 MCP server 插件时，只需在 plugin.json 配置 header，不需要修改后端认证逻辑。

memcore memory-update/lint 路径锁定：禁止写入系统自动记忆路径

结论：memory-update 和 memory-lint 的唯一操作路径锁定为 $PROJECT_DIR/.claude/memory/；严禁写入 ~/.claude/projects/*/memory/；两个技能执行期间不触发 auto memory 系统写入。

Why：Claude Code 的 auto memory 是 system-level 指令，在技能执行期间始终有效。若技能只在 description 中说"不推送远程"而无显式路径约束，AI 会在执行 memory-update/lint 时被 auto memory 指令并发触发，将内容写入系统级路径（~/.claude/projects/xxx/memory/），背离"项目本地 .claude/memory/ 是唯一权威"的初衷。

How to apply：两个技能均在正文最前加"⚠ 路径锁定"块（含禁止路径清单 + 执行前断言代码），memory-sync 的 Phase 3 加方向锁定注释（Phase 10 是唯一远程写入窗口）。未来新增操作本地记忆的技能也应遵循同等约束。

See Also：project_overview.md#已发布插件

SKILL.md frontmatter 只保留 name 和 description

结论：SKILL.md frontmatter 只写 name 和 description 两个字段，去掉 version。

Why：Claude Code 插件规范中 SKILL.md frontmatter 只定义了 name 和 description。version 字段不在规范内，silently ignored，且与 plugin.json 层面的版本管理重复。已从所有 huanxi skill 文件中移除。

How to apply：新建 SKILL.md 时只写这两个字段。description 字段写用户实际口语触发词（第三人称描述），不要用"当需要…时触发"的内部视角表达。

3.8 KiB Raw Blame History Unescape Escape