SkyJourneyandClaude Sonnet 4.6
ab6d78b096
- 新增 plugins/huanxi：Bearer Token 模式 MCP Server + 6 个工作流技能 （日报/负责人日报/周报/任务/组织），修正全部 MCP 工具签名 - 新增 plugins/memcore：memory-sync/update/lint 三技能记忆引擎， 修正 git add 范围避免误提交敏感文件 - CLAUDE.md：移除 version 字段示例，补充 userConfig/mcpServers 说明， 注入「记忆体系（会话启动必读）」区块 - .claude/memory/：初始化项目记忆索引（decisions/project_overview/ feedback_plugin_dev/lint_report） Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
61 lines
2.7 KiB
Markdown
61 lines
2.7 KiB
Markdown
---
|
||
name: 架构决策
|
||
description: Marketplace 设计中的关键技术决策及其原因
|
||
type: project
|
||
last_updated: 2026-05-01
|
||
commit: 0c46ed0
|
||
---
|
||
|
||
# 关键架构决策
|
||
|
||
## 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，不需要修改后端认证逻辑。
|
||
|
||
---
|
||
|
||
## 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` 字段写用户实际口语触发词（第三人称描述），不要用"当需要…时触发"的内部视角表达。
|