chore: memory-sync — 归档 Codex 插件骨架/bearer_token_env_var/不做Antigravity兼容等决策
新增 3 条 decisions.md 条目：Codex/ChatGPT 桌面应用插件骨架设计（三插件 共享 skills/、memcore 独立目录的原因）、Codex 侧 MCP Token 用 bearer_token_env_var 字段的踩坑与本地缓存刷新方法、调研后决定不做 Google Antigravity（agy）兼容。project_overview.md 已发布插件表格补 Codex 支持列，CLAUDE.md 补 Codex plugin.json 硬约束小节与并行结构说明。 memory-lint 顺带修了本机 shell 环境下 Phase 3C 快扫自引用排除逻辑失效 的问题（grep -r 输出不带 ./ 前缀导致误判），修复 1 处断链 + 1 处双链 缺失反向链接。 Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01LVyxoP4cDXeoQ3uAqLcEd2
This commit is contained in:
SkyJourney
co-authored by
Claude Sonnet 5
Claude Sonnet 5
parent
a64c64667c
commit
1606d73c41
@@ -1,9 +1,9 @@
|
||||
---
|
||||
name: 架构决策
|
||||
description: Marketplace 设计中的关键技术决策及其原因：无版本号/userConfig/Bearer Token/SKILL.md规范/路径锁定/memcore三项优化/memcore-shared共享层/lint_report保活/Base commit兜底/obsidian社区对标审查/memory-lint速度分档过期检测
|
||||
description: Marketplace 设计中的关键技术决策及其原因：无版本号/userConfig/Bearer Token/SKILL.md规范/路径锁定/memcore三项优化/memcore-shared共享层/lint_report保活/Base commit兜底/obsidian社区对标审查/memory-lint速度分档过期检测/Codex插件骨架与memcore-codex独立目录/Codex侧bearer_token_env_var/不做Antigravity兼容
|
||||
type: project
|
||||
last_updated: 2026-07-10
|
||||
commit: a13898b
|
||||
last_updated: 2026-08-22
|
||||
commit: a64c646
|
||||
---
|
||||
|
||||
# 关键架构决策
|
||||
@@ -24,7 +24,7 @@ commit: a13898b
|
||||
|
||||
**Why**：`sensitive: true` 将 token 存入系统钥匙链（或 `~/.claude/.credentials.json`），不会出现在 settings.json 中，避免随仓库提交泄露。Claude Code 安装插件时自动弹窗提示用户输入，体验好于环境变量。
|
||||
|
||||
**How to apply**：其他需要用户配置 API Key/Token 的插件，均应使用此模式，不要用 `${ENV_VAR}` 方式。
|
||||
**How to apply**：其他需要用户配置 API Key/Token 的插件，均应使用此模式，不要用 `${ENV_VAR}` 方式。此模式仅限 Claude Code 侧——Codex 没有等价钥匙链机制，见 [[decisions.md#Codex 侧 MCP Token 用 bearer_token_env_var，不用 ${VAR} 模板（2026-08-22）]]。
|
||||
|
||||
```json
|
||||
"userConfig": {
|
||||
@@ -174,3 +174,39 @@ commit: a13898b
|
||||
**How to apply**：新增/调整任何"距离上次更新多久算过期"的判定逻辑时，优先考虑用活跃度信号（提交频次、变更行数等）分档，而非固定日历阈值。常量集中在 `memcore-shared` 全局常量表单点维护，调整数值只改一处。
|
||||
|
||||
**See Also**：[[decisions.md#memcore-shared：路径锁定 + 全局常量的单一来源]]
|
||||
|
||||
---
|
||||
|
||||
## Codex/ChatGPT 桌面应用插件骨架——三个插件共享 skills/，memcore 独立目录（2026-08-22）
|
||||
|
||||
**结论**：huanxi、huanxi-admin、obsidian 的 Codex 版本通过在同一插件目录下新增 `.codex-plugin/plugin.json`（与 `.claude-plugin/plugin.json` 并列）实现，共用同一份 `skills/`；`memcore` 因为 Codex 插件校验器要求 `skills` 字段必须精确指向 `./skills`（不能自定义子路径），且 Codex 版记忆体系架构（`AGENTS.md` 会话入口 / `.codex/memory` 目录约定 / 无远程同步）与 Claude 版本质不同，无法共用同一份 `skills/` 内容，故新建独立插件目录 `plugins/memcore-codex/`；marketplace.json 里对外插件名仍叫 `memcore`（目录名与插件名不要求一致）。`memcore-codex` 以本机已装的 Codex 原生 memcore 技能为底稿，抽出 `memcore-shared` 共享 include，并吸纳了 Claude 版四项内容：过期检测速度分档、NEED-HUMAN 稳定 ID 保活、memory-update 锚点丢失兜底、更完整的 lint_report 模板。
|
||||
|
||||
**Why**：用本机已安装的 Codex `plugin-creator` 技能自带的 `validate_plugin.py` 实测确认——`skills` 字段规整化后必须精确等于 `"skills"`，`mcpServers` 字符串路径必须精确等于 `"./.mcp.json"`，且都必须在插件根目录（不能嵌套进 `.codex-plugin/`）；顶层 `interface` 块（displayName/shortDescription/longDescription/developerName/category/capabilities/defaultPrompt）是必填项，`hooks` 字段不被接受，`disable-model-invocation` 只能是 `false` 或不写。旧的 `feat/codex-marketplace` 分支骨架因为缺 `interface` 块、`.mcp.json` 放错位置，实际过不了这个校验（已删除该分支）。Codex 侧技能级"内部 include 不给用户直接调用"靠 `agents/openai.yaml` 的 `policy.allow_implicit_invocation: false` + description 措辞实现，不能像 Claude 侧那样用 frontmatter 禁用模型调用。
|
||||
|
||||
**How to apply**：新增/修改 Codex 插件时，先跑本机 `~/.codex/skills/.system/plugin-creator/scripts/validate_plugin.py <plugin-path>` 校验再算完成；技能内容若和 Claude 版能共用就共用同一 `skills/`，若架构本质不同（如需要独立会话入口/目录约定）就整个插件目录独立，不要硬塞进同一 `skills/`。
|
||||
|
||||
**See Also**：[[project_overview.md#已发布插件]]、[[decisions.md#memcore-shared：路径锁定 + 全局常量的单一来源]]、[[decisions.md#memcore lint_report 增量保活：稳定 ID + resolved 跳过]]、[[decisions.md#memory-update Phase 1 锚点丢失兜底]]
|
||||
|
||||
---
|
||||
|
||||
## Codex 侧 MCP Token 用 bearer_token_env_var，不用 ${VAR} 模板（2026-08-22）
|
||||
|
||||
**结论**：Codex（CLI + ChatGPT 桌面应用）没有等价于 Claude `userConfig` 钥匙链的插件级敏感配置机制。`.mcp.json` 里 HTTP 类型 MCP server 的 Bearer Token 必须用专用字段 `bearer_token_env_var: "ENV_VAR_NAME"`（只放变量名，不放值，由 Codex 进程启动时读取该环境变量），而不是在 `headers` 里写 `"Authorization": "Bearer ${VAR}"` 模板插值——后者不被 Codex 支持，会把 `${VAR}` 字面量原样发出去导致鉴权失败。
|
||||
|
||||
**Why**：查证 Codex 官方 MCP 配置文档（`config.toml` / `codex mcp add` 场景）确认专用字段是 `bearer_token_env_var` / `env_http_headers`；且有未解决的官方 issue（[openai/codex#24401](https://github.com/openai/codex/issues/24401)）明确指出插件打包的 MCP server 目前没有官方定义的用户密钥配置路径，环境变量注入（父进程启动前已设置）是当前唯一现实可用方式。实测踩坑：改完 `.mcp.json` 后本机 `codex plugin add` 缓存的旧版本（`~/.codex/plugins/cache/<marketplace>/<plugin>/<version>/`）不会自动更新，必须 `codex plugin marketplace upgrade <marketplace>` 刷新快照后重新 `codex plugin add` 才会生效。
|
||||
|
||||
**How to apply**：新增/修改任何 Codex 插件的 HTTP MCP server 配置，一律用 `bearer_token_env_var` 字段；环境变量的设置方式区分场景——CLI 用 shell `export`（写进启动脚本），ChatGPT 桌面应用（图形界面启动，不继承 shell）用 macOS `launchctl setenv` 或 Windows 系统环境变量。改完插件内容 push 后，本机测试前要先 `codex plugin marketplace upgrade <marketplace>` + 重新 `codex plugin add <plugin>@<marketplace>`，否则读到的还是装的时候那份缓存。
|
||||
|
||||
**See Also**：[[decisions.md#huanxi plugin 使用 userConfig 而非环境变量传 Token]]（对照：Claude 侧用 userConfig 钥匙链，Codex 侧被迫用环境变量，是两个平台能力差异，不是我们设计不一致）
|
||||
|
||||
---
|
||||
|
||||
## 不做 Antigravity（Google agy / Antigravity 2.0）兼容（2026-08-22）
|
||||
|
||||
**结论**：调研后决定暂不为 Google Antigravity CLI（agy）和 Antigravity 2.0 桌面应用建插件市场骨架。
|
||||
|
||||
**Why**：官方文档（antigravity.google/docs/cli/features/）确认 agy 支持插件（skills/agents/rules/MCP/hooks 打包），但**没有** marketplace 概念——无 `marketplace.json`、无"注册市场源"命令，只有 `agy plugin install <本地路径或 git URL>` 直接安装；网上搜到的"agy 支持 marketplace.json"等说法查证后均来自第三方社区工具（如 `agy-plugins-cli`），非 Google 官方能力。Antigravity 2.0 桌面应用官方文档完全没提插件/市场机制。该产品线是 Google I/O 2026 才发布，文档还在变动（schema 页面实测 404）。
|
||||
|
||||
**How to apply**：Claude Code 和 Codex 是当前团队实际使用的主流工具，继续投入维护；未来遇到新 AI 编程工具想接入本 marketplace 时，先确认该工具官方是否有稳定的 marketplace/plugin 协议（有市场索引格式 + 远程仓库注册命令），协议不成熟就先不投入，避免跟着一个还在剧烈变动的规范返工。
|
||||
|
||||
**See Also**：[[project_overview.md#已发布插件]]
|
||||
|
||||
Reference in New Issue
Block a user