SkyJourneyandClaude Sonnet 4.6
9c2f19b579
- 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>
73 lines
3.8 KiB
Markdown
73 lines
3.8 KiB
Markdown
---
|
||
name: 架构决策
|
||
description: Marketplace 设计中的关键技术决策及其原因
|
||
type: project
|
||
last_updated: 2026-05-08
|
||
commit: 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}` 方式。
|
||
|
||
```json
|
||
"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` 字段写用户实际口语触发词（第三人称描述），不要用"当需要…时触发"的内部视角表达。
|