From 3de9b054ef9de09cece2dd35ea2c7251a56206b1 Mon Sep 17 00:00:00 2001 From: SkyJourney Date: Sat, 22 Aug 2026 17:13:59 +0800 Subject: [PATCH] =?UTF-8?q?feat(codex):=20=E6=96=B0=E5=A2=9E=20Codex=20CLI?= =?UTF-8?q?=20=E6=8F=92=E4=BB=B6=E5=B8=82=E5=9C=BA=E6=94=AF=E6=8C=81?= =?UTF-8?q?=EF=BC=8C=E5=90=AB=E7=8B=AC=E7=AB=8B=20memcore-codex?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit huanxi/huanxi-admin/obsidian 复用 Claude Code 版技能内容，新增 .codex-plugin/plugin.json + .mcp.json（Token 走环境变量，Codex 无等价 钥匙链机制）。memcore 因架构差异（AGENTS.md 会话入口、.codex/memory 目录约定、无远程同步）独立新增 memcore-codex 插件：以本机已装的 Codex 原生版为底稿，抽出 memcore-shared 共享 include，并吸纳 Claude 版的速 度分档过期检测、NEED-HUMAN 稳定 ID 保活、兜底锚点、更完整报告模板四 项内容。新增 .agents/plugins/marketplace.json 收录四个插件，均通过 Codex 官方 validate_plugin.py 校验。 README/CHANGELOG 同步补充双端安装配置引导。删除已被取代的旧 feat/codex-marketplace 骨架分支和已合并的 feat/memcore-optimizations 分支。 Co-Authored-By: Claude Sonnet 5 Claude-Session: https://claude.ai/code/session_01LVyxoP4cDXeoQ3uAqLcEd2 --- .agents/plugins/marketplace.json | 56 ++++ CHANGELOG.md | 2 + README.md | 60 +++- .../huanxi-admin/.codex-plugin/plugin.json | 19 ++ plugins/huanxi-admin/.mcp.json | 11 + plugins/huanxi/.codex-plugin/plugin.json | 19 ++ plugins/huanxi/.mcp.json | 11 + .../memcore-codex/.codex-plugin/plugin.json | 18 ++ .../skills/memcore-shared/SKILL.md | 74 +++++ .../skills/memcore-shared/agents/openai.yaml | 6 + .../memcore-codex/skills/memory-lint/SKILL.md | 304 ++++++++++++++++++ .../skills/memory-lint/agents/openai.yaml | 7 + .../memcore-codex/skills/memory-sync/SKILL.md | 158 +++++++++ .../skills/memory-sync/agents/openai.yaml | 7 + .../skills/memory-update/SKILL.md | 199 ++++++++++++ .../skills/memory-update/agents/openai.yaml | 7 + plugins/obsidian/.codex-plugin/plugin.json | 18 ++ .../skills/obsidian-workflow-pkm/SKILL.md | 2 +- 18 files changed, 966 insertions(+), 12 deletions(-) create mode 100644 .agents/plugins/marketplace.json create mode 100644 plugins/huanxi-admin/.codex-plugin/plugin.json create mode 100644 plugins/huanxi-admin/.mcp.json create mode 100644 plugins/huanxi/.codex-plugin/plugin.json create mode 100644 plugins/huanxi/.mcp.json create mode 100644 plugins/memcore-codex/.codex-plugin/plugin.json create mode 100644 plugins/memcore-codex/skills/memcore-shared/SKILL.md create mode 100644 plugins/memcore-codex/skills/memcore-shared/agents/openai.yaml create mode 100644 plugins/memcore-codex/skills/memory-lint/SKILL.md create mode 100644 plugins/memcore-codex/skills/memory-lint/agents/openai.yaml create mode 100644 plugins/memcore-codex/skills/memory-sync/SKILL.md create mode 100644 plugins/memcore-codex/skills/memory-sync/agents/openai.yaml create mode 100644 plugins/memcore-codex/skills/memory-update/SKILL.md create mode 100644 plugins/memcore-codex/skills/memory-update/agents/openai.yaml create mode 100644 plugins/obsidian/.codex-plugin/plugin.json diff --git a/.agents/plugins/marketplace.json b/.agents/plugins/marketplace.json new file mode 100644 index 0000000..0826315 --- /dev/null +++ b/.agents/plugins/marketplace.json @@ -0,0 +1,56 @@ +{ + "name": "yixiong-codex-hub", + "interface": { + "displayName": "蚁熊 Codex 技能市场" + }, + "plugins": [ + { + "name": "huanxi", + "source": { + "source": "local", + "path": "./plugins/huanxi" + }, + "policy": { + "installation": "AVAILABLE", + "authentication": "ON_INSTALL" + }, + "category": "Productivity" + }, + { + "name": "huanxi-admin", + "source": { + "source": "local", + "path": "./plugins/huanxi-admin" + }, + "policy": { + "installation": "AVAILABLE", + "authentication": "ON_INSTALL" + }, + "category": "Productivity" + }, + { + "name": "memcore", + "source": { + "source": "local", + "path": "./plugins/memcore-codex" + }, + "policy": { + "installation": "AVAILABLE", + "authentication": "ON_INSTALL" + }, + "category": "Productivity" + }, + { + "name": "obsidian", + "source": { + "source": "local", + "path": "./plugins/obsidian" + }, + "policy": { + "installation": "AVAILABLE", + "authentication": "ON_INSTALL" + }, + "category": "Productivity" + } + ] +} diff --git a/CHANGELOG.md b/CHANGELOG.md index dd4fecd..14f3882 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,6 +4,8 @@ ## 2026-08-22 +- **新增 Codex CLI 支持**：`huanxi`/`huanxi-admin`/`obsidian` 复用 Claude Code 版技能内容，新增 `.codex-plugin/plugin.json` + `.mcp.json`（Token 走环境变量 `HUANXI_TOKEN`/`HUANXI_ADMIN_TOKEN`，Codex 没有等价的钥匙链机制）；`memcore` 因架构差异（`AGENTS.md` 会话入口、`.codex/memory` 目录约定、无远程同步）独立新增 `memcore-codex` 插件，以本机已装的 Codex 原生版为底稿，吸纳了 Claude 版的速度分档过期检测、NEED-HUMAN 稳定 ID 保活、兜底锚点、更完整报告模板四项内容，并抽出 `memcore-shared` 共享 include。新增 `.agents/plugins/marketplace.json` 收录四个插件，均通过 Codex 官方 `validate_plugin.py` 校验 +- README 补充 Claude Code / Codex CLI 双端的安装命令与配置引导（huanxi Token 获取步骤、Codex 环境变量注入方式、memcore 两版本架构差异说明） - **`huanxi` 全面升级到 v2 技能组**：技能内容从寰汐 v1 全面替换为 v2，`huanxi-org`/`huanxi-weekly` 等 v1 专属技能下线，新增 `huanxi-issue`/`huanxi-lookup`/`huanxi-meeting`；MCP 连接与 Token 获取方式同步更新为寰汐「个人中心 → MCP Token 管理」自助生成 - **新增 `huanxi-admin` 插件**：管理端 4 个技能（汇报盘点、模块与成员配置、运维简报），需要后台管理员发放 `hxa_` Token，普通员工无需安装。此前一直卡在"寰汐 v2 未部署到生产域名前不推送"这条约束，随寰汐 v1.0.0 生产切换完成后正式首发 diff --git a/README.md b/README.md index c3bf1de..d019c8b 100644 --- a/README.md +++ b/README.md @@ -1,9 +1,11 @@ -# 蚁熊 Claude Code 技能市场 +# 蚁熊技能市场 -蚁熊团队内部的 Claude Code Plugin Marketplace——汇聚团队在真实业务场景里打磨出来的技能与工作流插件，从项目管理到知识库协作，从代码审查到数据工程，装上它，让 Claude Code 更懂蚁熊。 +蚁熊团队内部的插件市场，同时支持 **Claude Code** 和 **Codex CLI**——汇聚团队在真实业务场景里打磨出来的技能与工作流插件，从项目管理到知识库协作，从代码审查到数据工程，装上它，让 AI 编程助手更懂蚁熊。 ## 快速安装 +### Claude Code + ``` /plugin marketplace add https://gitea.rk-health.com/yixiong/yixiong-claude-marketplace.git ``` @@ -19,31 +21,67 @@ 已安装的插件会在会话启动时自动检测更新——本仓库不走语义化版本号，每次推送 `main` 分支即视为新版本。 +### Codex CLI + +``` +codex plugin marketplace add https://gitea.rk-health.com/yixiong/yixiong-claude-marketplace.git +``` + +添加市场源之后，按需安装具体插件： + +``` +codex plugin add huanxi@yixiong-codex-hub +codex plugin add huanxi-admin@yixiong-codex-hub +codex plugin add memcore@yixiong-codex-hub +codex plugin add obsidian@yixiong-codex-hub +``` + +安装完成后开一个新会话，Codex 才会加载新装的技能和 MCP 工具。 + +> Codex 侧的插件清单独立维护在 [`.agents/plugins/marketplace.json`](./.agents/plugins/marketplace.json)。除 `memcore` 外，其余三个插件与 Claude Code 版共用同一份 `skills/`；`memcore` 因为架构差异（会话入口、记忆目录约定、有无远程同步都不同）走的是独立目录 [`plugins/memcore-codex/`](./plugins/memcore-codex)，两边分开维护。 + ## 插件一览 -| 插件 | 技能数 | 适用场景 | 谁需要装 | -|---|---|---|---| -| [`huanxi`](./plugins/huanxi) | 7 | 寰汐企业管理系统个人端——日报、负责人日报、任务、议题、会议、组织检索 | 全员 | -| [`huanxi-admin`](./plugins/huanxi-admin) | 4 | 寰汐管理端——汇报盘点、模块与成员配置、运维简报 | 需要后台管理员发放 `hxa_` Token 的管理岗 | -| [`memcore`](./plugins/memcore) | 4 | 项目记忆体系核心引擎——跨会话记忆的同步/增量更新/健康校验 | 用 Claude Code 做长期项目的开发者 | -| [`obsidian`](./plugins/obsidian) | 10 | Obsidian 知识库全套协作工作流——vault 管理、搜索图谱、Bases、Canvas、每日笔记等 | 用 Obsidian 做知识管理的人 | +| 插件 | 技能数 | 适用场景 | 谁需要装 | Claude Code | Codex CLI | +|---|---|---|---|:---:|:---:| +| [`huanxi`](./plugins/huanxi) | 7 | 寰汐企业管理系统个人端——日报、负责人日报、任务、议题、会议、组织检索 | 全员 | ✅ | ✅ | +| [`huanxi-admin`](./plugins/huanxi-admin) | 4 | 寰汐管理端——汇报盘点、模块与成员配置、运维简报 | 需要后台管理员发放 `hxa_` Token 的管理岗 | ✅ | ✅ | +| [`memcore`](./plugins/memcore) / [`memcore-codex`](./plugins/memcore-codex) | 4 | 项目记忆体系核心引擎——跨会话记忆的同步/增量更新/健康校验 | 用 Claude Code 或 Codex 做长期项目的开发者 | ✅ | ✅ | +| [`obsidian`](./plugins/obsidian) | 10 | Obsidian 知识库全套协作工作流——vault 管理、搜索图谱、Bases、Canvas、每日笔记等 | 用 Obsidian 做知识管理的人 | ✅ | ✅ | ### huanxi / huanxi-admin -寰汐是蚁熊内部的项目管理与团队协同系统。`huanxi` 以你本人的身份操作，权限与网页端一致，安装后需要在寰汐「个人中心 → MCP Token 管理」自助生成一个 `hxp_` 开头的 Token 填进插件配置。`huanxi-admin` 是全量管理视角，Token 由后台管理员单独发放，高危操作（账号启停、提权、删除）不在这个端点里，普通员工不需要装。 +寰汐是蚁熊内部的项目管理与团队协同系统。`huanxi` 以你本人的身份操作，权限与网页端一致；`huanxi-admin` 是全量管理视角，高危操作（账号启停、提权、删除）不在这个端点里，普通员工不需要装。 + +**配置步骤：** + +1. 去寰汐「个人中心 → MCP Token 管理」自助生成一个 `hxp_` 开头的 Token（`huanxi-admin` 的 `hxa_` Token 由后台管理员单独发放，普通员工无需申请）。 +2. **Claude Code**：执行 `/plugin install` 时会提示输入 Token，直接粘贴即可——存放在系统钥匙链，不会明文写入配置文件。 +3. **Codex CLI**：Codex 没有等价的钥匙链机制，Token 走环境变量注入。启动 Codex 前设置： + + ```bash + export HUANXI_TOKEN=hxp_你的token # huanxi 个人端 + export HUANXI_ADMIN_TOKEN=hxa_你的token # huanxi-admin 管理端 + ``` + + 建议写进 shell 的启动脚本（`~/.zshrc` / `~/.bashrc`），避免每次开新终端都要重新导出。 ### memcore -给 Claude Code 加一套跨会话持久记忆的引擎：`memory-sync` 做全量同步（读远程补充、写本地权威、推送远程），`memory-update` 做增量写入，`memory-lint` 做健康校验（孤儿引用、断链、内容矛盾、过期检测）。不依赖 MCP，纯技能实现。 +给 AI 编程助手加一套跨会话持久记忆的引擎：`memory-sync` 做全量同步、`memory-update` 做增量写入、`memory-lint` 做健康校验（孤儿引用、断链、内容矛盾、过期检测）。不依赖 MCP，纯技能实现，**无需任何配置，安装即用**。 + +Claude Code 版（[`plugins/memcore`](./plugins/memcore)）以 `.claude/memory/` 为唯一权威，`memory-sync` 会额外和 `~/.claude/projects/*/memory/` 做远程镜像同步，支持多机协作。Codex 版（[`plugins/memcore-codex`](./plugins/memcore-codex)）架构不同：会话入口是 `AGENTS.md` 而非 `CLAUDE.md`，记忆目录优先复用已有的 `.claude/memory/`、否则落在 `.codex/memory/`，且**不做远程同步**——Codex 没有等价的跨机器 auto memory 层，记忆只落在当前仓库内。两个版本共享同一套 `SYNTHESIS_THRESHOLD`、过期检测速度分档等常量设计，但各自独立维护。 ### obsidian -检测到项目里有 `.obsidian/` 目录会自动激活，覆盖 vault 管理、全文与图谱搜索、frontmatter、任务、每日笔记、Bases 数据库、Canvas 视觉层、版本历史、插件配置、PKM 编排十个技能，对标社区里比较成熟的 Obsidian 技能实现后做了扩展。 +检测到项目里有 `.obsidian/` 目录会自动激活，覆盖 vault 管理、全文与图谱搜索、frontmatter、任务、每日笔记、Bases 数据库、Canvas 视觉层、版本历史、插件配置、PKM 编排十个技能，对标社区里比较成熟的 Obsidian 技能实现后做了扩展。**无需任何配置**，Claude Code 和 Codex CLI 共用同一份技能内容。 ## 开发 给这个市场新增插件、技能实现规范、`marketplace.json`/`plugin.json` 格式说明，见 [CLAUDE.md](./CLAUDE.md)。 +Codex 插件的 `.codex-plugin/plugin.json` 有几个硬性约束（用本机 `plugin-creator` 技能自带的 `validate_plugin.py` 校验）：`skills` 字段必须精确指向 `./skills`、`mcpServers` 字符串路径必须精确指向 `./.mcp.json`（都在插件根目录，不能嵌套在 `.codex-plugin/` 里），且顶层 `interface` 块（`displayName`/`shortDescription`/`longDescription`/`developerName`/`category`/`capabilities`/`defaultPrompt`）是必填项。 + ## 更新记录 见 [CHANGELOG.md](./CHANGELOG.md)。 diff --git a/plugins/huanxi-admin/.codex-plugin/plugin.json b/plugins/huanxi-admin/.codex-plugin/plugin.json new file mode 100644 index 0000000..2ed7a4a --- /dev/null +++ b/plugins/huanxi-admin/.codex-plugin/plugin.json @@ -0,0 +1,19 @@ +{ + "name": "huanxi-admin", + "version": "1.0.0", + "description": "寰汐企业管理系统 · 管理端插件，全量视角，含汇报盘点、模块与成员配置、运维简报三个工作流技能。需要管理员发放的 hxa_ Token，高危操作（账号启停/提权/删除）不在此端点。", + "author": { + "name": "姜顺志" + }, + "skills": "./skills", + "mcpServers": "./.mcp.json", + "interface": { + "displayName": "寰汐 · 管理端", + "shortDescription": "寰汐管理端汇报/模块/运维工作流", + "longDescription": "寰汐企业管理系统管理端插件，全量管理视角，跳过模块角色过滤。覆盖汇报盘点、模块与成员配置、运维简报三个工作流技能。需要后台管理员在「系统 → Admin Token」生成 hxa_ 开头的 Token 并配置为环境变量 HUANXI_ADMIN_TOKEN；普通员工无需安装本插件。账号启停、提权、删除等高危操作不在本端点，需去网页后台操作。", + "developerName": "蚁熊团队", + "category": "Productivity", + "capabilities": ["Interactive", "Write"], + "defaultPrompt": "帮我看一下本周的汇报盘点情况" + } +} diff --git a/plugins/huanxi-admin/.mcp.json b/plugins/huanxi-admin/.mcp.json new file mode 100644 index 0000000..98ff1fb --- /dev/null +++ b/plugins/huanxi-admin/.mcp.json @@ -0,0 +1,11 @@ +{ + "mcpServers": { + "huanxi-admin": { + "type": "http", + "url": "https://huanxi.office.yixiong-tech.com/admin-mcp/", + "headers": { + "Authorization": "Bearer ${HUANXI_ADMIN_TOKEN}" + } + } + } +} diff --git a/plugins/huanxi/.codex-plugin/plugin.json b/plugins/huanxi/.codex-plugin/plugin.json new file mode 100644 index 0000000..7664dd7 --- /dev/null +++ b/plugins/huanxi/.codex-plugin/plugin.json @@ -0,0 +1,19 @@ +{ + "name": "huanxi", + "version": "1.0.0", + "description": "寰汐企业管理系统 · 个人端插件，含日报、负责人日报、任务、议题、会议、组织检索七个工作流技能，自动配置个人端 MCP 连接。", + "author": { + "name": "姜顺志" + }, + "skills": "./skills", + "mcpServers": "./.mcp.json", + "interface": { + "displayName": "寰汐 · 个人端", + "shortDescription": "寰汐日报/任务/议题/会议工作流", + "longDescription": "寰汐企业管理系统个人端插件：以你本人身份操作，权限与网页端一致。覆盖日报、负责人日报、任务管理、议题跟踪、会议纪要、组织检索七个工作流技能。安装后需在寰汐「个人中心 → MCP Token 管理」自助生成 hxp_ 开头的 Token，并配置为环境变量 HUANXI_TOKEN。", + "developerName": "蚁熊团队", + "category": "Productivity", + "capabilities": ["Interactive", "Write"], + "defaultPrompt": "帮我看看今天有哪些任务和待办" + } +} diff --git a/plugins/huanxi/.mcp.json b/plugins/huanxi/.mcp.json new file mode 100644 index 0000000..2584772 --- /dev/null +++ b/plugins/huanxi/.mcp.json @@ -0,0 +1,11 @@ +{ + "mcpServers": { + "huanxi": { + "type": "http", + "url": "https://huanxi.office.yixiong-tech.com/mcp/", + "headers": { + "Authorization": "Bearer ${HUANXI_TOKEN}" + } + } + } +} diff --git a/plugins/memcore-codex/.codex-plugin/plugin.json b/plugins/memcore-codex/.codex-plugin/plugin.json new file mode 100644 index 0000000..a3f9a3d --- /dev/null +++ b/plugins/memcore-codex/.codex-plugin/plugin.json @@ -0,0 +1,18 @@ +{ + "name": "memcore", + "version": "1.0.0", + "description": "Codex 记忆体系核心引擎。提供 memcore-shared（内部共享约定）+ memory-sync（全量同步编排）+ memory-update（增量写入）+ memory-lint（健康校验）。Codex 版本不使用远程记忆，记忆只落在当前仓库/项目目录内。", + "author": { + "name": "姜顺志" + }, + "skills": "./skills", + "interface": { + "displayName": "Memcore", + "shortDescription": "项目本地记忆体系核心引擎", + "longDescription": "给 Codex 加一套跨会话持久的项目本地记忆引擎：memory-sync 做完整同步周期（Git 检查 → 读取现有记忆 → 增量更新 → 健康校验 → 维护 AGENTS.md 启动引导），memory-update 做增量写入，memory-lint 做健康校验（孤儿/幽灵检测、双向引用、内容矛盾、按提交速度分档的过期检测）。不依赖 MCP，纯技能实现；不使用远程记忆，也不读写 Codex 原生 Memories。", + "developerName": "蚁熊团队", + "category": "Productivity", + "capabilities": ["Interactive", "Write"], + "defaultPrompt": "帮我同步一下这个项目的本地记忆" + } +} diff --git a/plugins/memcore-codex/skills/memcore-shared/SKILL.md b/plugins/memcore-codex/skills/memcore-shared/SKILL.md new file mode 100644 index 0000000..94bf0cf --- /dev/null +++ b/plugins/memcore-codex/skills/memcore-shared/SKILL.md @@ -0,0 +1,74 @@ +--- +name: memcore-shared +description: "memcore 内部共享约定：记忆目录选择优先级、会话入口术语、禁止触碰的路径、synthesis/过期检测阈值常量。仅供 memory-sync、memory-update、memory-lint 三个技能在 Phase 0 内部 Read 引用，不用于直接回答用户问题或独立执行任务。" +--- + +# memcore-shared + +三个主技能（memory-sync / memory-update / memory-lint）的内部共享 include。**用户不会直接调用本技能**，三个主技能在开始执行前必须先 Read 本文件载入以下约束。 + +--- + +## 统一术语 + +- `SESSION_GUIDE_FILE`：`AGENTS.md`，Codex 项目的会话启动入口锚点。 +- `PROJECT_MEMORY_DIR`：项目内唯一记忆目录，取 `.claude/memory` 或 `.codex/memory`（选择规则见下）。 +- `MEMORY_INDEX`：`PROJECT_MEMORY_DIR/MEMORY.md`。 + +修改 `SESSION_GUIDE_FILE`、`MEMORY_INDEX` 或任何记忆文件时，优先使用小范围补丁，不要整文件重写。记忆变更和代码变更必须分开说明、分开确认。 + +--- + +## PROJECT_MEMORY_DIR 选择优先级 + +三个主技能执行前都必须先按以下优先级确定唯一记忆目录： + +1. 若 `AGENTS.md` 已含记忆体系区块，优先读取该区块中记录的记忆目录；目录存在则使用它。 +2. 若 `$PROJECT_DIR/.claude/memory/` 存在，使用它——视为复用现有 Claude 项目记忆。 +3. 若 `$PROJECT_DIR/CLAUDE.md` 存在但 `.claude/memory/` 不存在，先读取 `CLAUDE.md` 中与记忆体系相关的说明；只在用户明确要求建立结构化记忆目录时才创建 `.codex/memory/`。 +4. 若 `$PROJECT_DIR/.codex/memory/` 存在，使用它。 +5. 以上都不存在，需要创建记忆时使用 `$PROJECT_DIR/.codex/memory/`，但创建前必须向用户说明将建立的目录结构和基础文件，并等待确认。 + +关键规则： + +- `AGENTS.md` 是会话入口锚点，不是记忆目录本身。 +- 已有 `CLAUDE.md` 或 `.claude/memory/` 时直接引用现有内容，不重复添加同类记忆引导。 +- 不把 `.claude/memory/` 复制到 `.codex/memory/`，也不反向复制——两者只能存在一个作为 `PROJECT_MEMORY_DIR`。 + +--- + +## 禁止触碰的路径 + +| 路径 | 原因 | +|---|---| +| `~/.claude/projects/*/memory/` | Claude 侧系统 auto memory 路径。Codex 版本不使用远程记忆，不维护跨机器镜像，严禁读写 | +| `~/.codex/memories/` | Codex 原生 Memories，是个人本地召回层，不是团队可审查的项目事实来源，不作为本套记忆体系的后端 | +| `$PROJECT_DIR` 之外任何其他路径 | 跨项目污染 | + +必须可审查、可协作、可复现的项目事实一律写入 `AGENTS.md`、`CLAUDE.md`、`.claude/memory/` 或 `.codex/memory/`，不写入上表任何路径。 + +--- + +## 全局常量 + +| 常量 | 值 | 含义 | 使用位置 | +|---|---|---|---| +| `SYNTHESIS_THRESHOLD` | `3` | 跨文件引用数 ≥ 此值即为 synthesis 升级候选 | memory-update Phase 3、memory-lint Phase 3 & 8 | +| `LINT_STALE_MIN_DAYS` | `7` | `last_updated` 不足此天数 → 跳过过期检测 | memory-lint Phase 5 | +| `LINT_HIGH_VELOCITY` | `1.0`（次/天） | 全仓库提交速度 ≥ 此值 → 高频迭代区 → ERROR | memory-lint Phase 5 | +| `LINT_LOW_VELOCITY` | `0.3`（次/天） | 全仓库提交速度 ≥ 此值 → 中频迭代区 → WARN | memory-lint Phase 5 | +| `LINT_STALE_ABSOLUTE_DAYS` | `180` | 速度低于 `LINT_LOW_VELOCITY` 时的绝对兜底天数 → WARN | memory-lint Phase 5 | + +子技能引用常量时使用上述名称，调整阈值只需修改本文件单一来源。可由 `MEMORY.md` 头部 `` 覆盖 `LINT_STALE_MIN_DAYS`。 + +--- + +## 引用约定 + +子技能开头标准引用句： + +```markdown +**前置约束：先 Read `../memcore-shared/SKILL.md`（记忆目录选择优先级 + 禁止路径 + 常量）** +``` + +读取后，子技能内所有出现的 `$PROJECT_DIR`、`PROJECT_MEMORY_DIR`、`MEMORY_INDEX`、`SESSION_GUIDE_FILE` 及上述常量均按本文件定义执行。 diff --git a/plugins/memcore-codex/skills/memcore-shared/agents/openai.yaml b/plugins/memcore-codex/skills/memcore-shared/agents/openai.yaml new file mode 100644 index 0000000..deb330e --- /dev/null +++ b/plugins/memcore-codex/skills/memcore-shared/agents/openai.yaml @@ -0,0 +1,6 @@ +interface: + display_name: "Memcore Shared" + short_description: "memcore 内部共享约定（不直接调用）" + +policy: + allow_implicit_invocation: false diff --git a/plugins/memcore-codex/skills/memory-lint/SKILL.md b/plugins/memcore-codex/skills/memory-lint/SKILL.md new file mode 100644 index 0000000..e419105 --- /dev/null +++ b/plugins/memcore-codex/skills/memory-lint/SKILL.md @@ -0,0 +1,304 @@ +--- +name: memory-lint +description: 检查仓库/项目本地记忆目录的健康状况，修复结构性问题并生成 lint_report.md。用于校验 MEMORY.md 索引、孤儿/幽灵文件、双向引用、内容矛盾、按提交速度分档的过期检测和可推断内容污染。Codex 版本只读写项目本地记忆；若仓库已有 CLAUDE.md 或 .claude/memory/，直接引用现有 Claude 记忆内容，不重复创建。 +--- + +# memory-lint + +健康检查项目本地记忆目录。会话目录视为 `$PROJECT_DIR`。 + +**前置约束：先 Read `../memcore-shared/SKILL.md`**（记忆目录选择优先级 + 禁止路径 + 常量），其约束在本技能全程生效。 + +修改 `MEMORY_INDEX`、`lint_report.md` 或任何记忆文件时，优先使用小范围补丁；不要整文件重写。记忆变更和代码变更必须分开说明、分开确认。 + +若目标记忆目录不存在，输出缺失说明并建议先执行 `memory-sync` 或 `memory-update` 初始化。 + +## Phase 0 - 读取状态 + +读取： + +- `MEMORY.md` +- 记忆目录内全部 `*.md` +- `Base commit` +- `Last synced` + +提取索引文件集合 `$INDEX_FILES` 和磁盘文件集合 `$DISK_FILES`。 + +## Phase 1-2 - 孤儿与幽灵检测 + +| 检查 | 定义 | 级别 | AUTO-FIX | +| --- | --- | --- | --- | +| 孤儿 | 索引有，磁盘无 | ERROR | 从 `MEMORY.md` 删除该条目 | +| 幽灵 | 磁盘有，索引无 | WARN | 补入索引 | + +幽灵类型推断（按优先级匹配）： + +- `synonyms.md`（精确匹配） → reference +- `user_*` → user +- `project_*` 或 `decisions.md` → project +- `feedback*` → feedback +- `reference*` → reference +- `synthesis_*` → synthesis +- 其他默认 project + +排除 `MEMORY.md`、`lint_report.md`。 + +## Phase 3 - 交叉引用完整性 + +### 3A 存在性检测 + 引用计数构建 + +扫描所有 `[[filename.md#section]]`，构建： + +- 引用表：`源文件#源章节 -> 目标文件#目标章节` +- 文件级被引用计数 `$REF_COUNT`（按源文件去重）→ Phase 7 写入 MEMORY.md「引用」列 +- decisions 和 feedback 条目级引用计数 `$ITEM_REF_COUNT`（按源文件去重）→ Phase 8 写入 lint_report.md，供 `memory-update` 反向触发消费 + +| 情况 | 级别 | 动作 | +| --- | --- | --- | +| 目标文件不存在 | ERROR | NEED-HUMAN | +| 目标章节缺失，且存在高相似标题 | WARN | AUTO-FIX 更新引用 | +| 目标章节缺失，且无相似项 | WARN | NEED-HUMAN | + +### 3B 对称性检测（双链闭环） + +复用 3A 引用表，对每条 `A#x -> B#y` 检查 B 的 `## y` 是否含任意 `[[A` 引用（不要求精确章节）。 + +- 级别：WARN +- AUTO-FIX：B 的目标章节末尾追加 `**See Also：** [[A#x]]` +- 边界：`lint_report.md` 不参与；B 整文件无对 A 任何引用 → AUTO-FIX；B 有引用但不在目标章节 → 仅 WARN 不自动修改 + +双链 AUTO-FIX 阈值：缺失反链不超过 5 条且涉及文件不超过 3 个时可以自动补齐；超过阈值、跨多个主题、或将触碰 `user_profile.md` / `synthesis_*.md` 时不自动修改，写入 `lint_report.md` 等待确认。 + +## Phase 4-pre - 等价表述加载 + +矛盾检测前先加载 `$PROJECT_MEMORY_DIR/synonyms.md`（可选文件）： + +```bash +[ -f "$PROJECT_MEMORY_DIR/synonyms.md" ] && \ + grep -v "^#\|^---\|^$\|^name:\|^description:\|^type:" \ + "$PROJECT_MEMORY_DIR/synonyms.md" +# 输出每行一个等价组（逗号分隔），大小写不敏感，存入 $SYNONYMS_GROUPS +``` + +`synonyms.md` 格式（用户自行在项目内创建和维护）： + +```markdown +--- +name: 等价表述清单 +description: 矛盾检测等价词表，同组词视为相同概念 +type: reference +--- + +# 等价表述清单 +> 每行一组，逗号分隔，大小写不敏感 + +PostgreSQL, PG, Postgres, postgresql +JWT, JSON Web Token +``` + +判定规则：两处描述中出现的技术术语若属同一等价组，跳过，不纳入矛盾候选。无 `synonyms.md` 时，仅检测直接数值/版本冲突，对措辞差异不报告。 + +## Phase 4 - 内容矛盾 + +| 维度 | 检查 | +| --- | --- | +| decisions vs feedback | 决策与协作规范是否冲突 | +| decisions vs 架构/依赖文件 | 是否与当前依赖清单（如 `package.json`、`requirements.txt`、`pom.xml`）实际内容冲突 | +| 多个 feedback 文件 | 是否重复或矛盾 | +| synthesis vs decisions | 归档结论是否抵触现有决策 | +| 合并残留标记 | 是否含 `` | + +矛盾判定门槛（过 synonyms.md 等价检查后）： + +| 情况 | 处理 | +| --- | --- | +| 同主题，等价组内术语不同 | 跳过，不报告 | +| 同主题，结论相反 | WARN → NEED-HUMAN | +| 同主题，数值或版本直接冲突 | ERROR → NEED-HUMAN | +| 仅措辞不同，无直接逻辑冲突 | 跳过（宁漏报不误报） | + +合并残留标记的 NEED-HUMAN 条目必须包含： + +- 位置：文件名、章节标题、标记内容。 +- Checklist：Q1 当前本地版本是否正确？Q2 另一版本是否有当前版本没有的有效信息？Q3 两者是否可以合并为单一表述？ +- 决策矩阵：Q2 否 → 删除 `[合并待审]` 或分歧段落和标记；Q2 是 + Q3 是 → 合并为单一表述后删除标记；Q2 是 + Q3 否 → 保留两段内容，但清除 HTML 标记并说明适用边界。 + +## Phase 5 - 过期检测（提交速度分档） + +不用固定天数二级阈值，改用「自 `last_updated` 以来的全仓库提交速度」判断过期风险的严重程度：高频迭代项目下 7 天未同步就可能已经漂移，低活跃项目下 180 天未动也可能仍然准确。阈值常量由 `memcore-shared` 定义。 + +```bash +# days_since：last_updated 距今天数 +days_since=$(( ($(date +%s) - $(date -d "$last_updated" +%s)) / 86400 )) + +# 不足 LINT_STALE_MIN_DAYS（默认 7 天）→ 跳过本文件的过期检测 +if [ "$days_since" -lt 7 ]; then + continue +fi + +# commits_since：全仓库自 last_updated 以来的提交数 +commits_since=$(git -C "$PROJECT_DIR" log --oneline --since="$last_updated" -- . | wc -l) + +# velocity：提交速度（次/天） +velocity=$(echo "scale=2; $commits_since / $days_since" | bc) +``` + +分级（可由 `MEMORY.md` 头部 `` 覆盖 `LINT_STALE_MIN_DAYS`）： + +| 条件 | 级别 | 语义 | +| --- | --- | --- | +| `velocity ≥ LINT_HIGH_VELOCITY`（默认 1.0） | ERROR | 高频迭代区，未同步几乎必然漂移 | +| `LINT_LOW_VELOCITY ≤ velocity < LINT_HIGH_VELOCITY`（默认 0.3~1.0） | WARN | 中频迭代，需人工确认是否漂移 | +| `velocity < LINT_LOW_VELOCITY` 且 `days_since < LINT_STALE_ABSOLUTE_DAYS`（默认 180） | — | 低活跃期，不判定过期 | +| `velocity < LINT_LOW_VELOCITY` 且 `days_since ≥ LINT_STALE_ABSOLUTE_DAYS` | WARN | 绝对兜底，防止彻底沉寂的记忆永不复查 | + +不要只因为日期老就自动刷新 `last_updated`。若内容仍有效，写入 NEED-HUMAN 让用户确认是否仅刷新日期；若内容与项目推进不符，标记为语义过时并给出证据位置。 + +## Phase 6 - 可推断内容污染 + +污染特征：大量具体文件路径、类名、方法签名、git 流水账、可从依赖文件直接读取的版本号列表。 + +**边界**：架构层级描述（"认证模块提供 JWT + OAuth2 双协议"）保留；具体类名/方法/路径列表删除或建议改写。 + +## Phase 7 - 执行 AUTO-FIX + +只允许修复结构性问题： + +1. 移除索引孤儿。 +2. 补入索引幽灵。 +3. 更新高置信断链引用。 +4. 在阈值内补齐双向链接；超过阈值则写入 NEED-HUMAN。 +5. 刷新 `MEMORY.md` 的「引用」列（基于 `$REF_COUNT`）：表格统一 5 列 `| 文件 | 描述 | 类型 | 引用 | Commit |`；「引用」值 ≥ `SYNTHESIS_THRESHOLD` 加 `*`（如 `5*`），否则显示数字；按引用次数倒序排列，同次数按类型序：user → project → feedback → reference → synthesis → lint。 + +不要自动修改业务结论、技术决策、用户偏好或主观归档内容。 + +## Phase 8 - 生成 lint_report.md + +### Phase 8-pre - NEED-HUMAN 稳定 ID 与已 resolved 保活 + +**目的**：用户在 `lint_report.md` 中给某个 NEED-HUMAN 条目添加 `` 标记后，下次 lint 不再重复列出该条目（即使问题尚未真正修复，用户已表达「不处理」意图）。 + +**ID 生成规则**： + +```bash +# 每个 NEED-HUMAN 条目计算稳定 ID（与执行时间无关，仅与"问题本体"有关） +# 输入：phase 编号 + 目标文件 + 目标章节 + 问题关键事实 +# 输出：sha1 前 8 位 +gen_id() { + printf '%s|%s|%s|%s' "$1" "$2" "$3" "$4" | sha1sum | cut -c1-8 +} + +# 示例： +# Phase 3A 断链：gen_id "3A" "decisions.md" "## 数据库选型" "[[synthesis_arch_xxx.md]]" +# Phase 4 矛盾：gen_id "4" "decisions.md+project_overview.md" "数据库选型" "PostgreSQL vs MySQL" +# Phase 5 过期：gen_id "5" "project_progress.md" "" "stale-86d" +# Phase 6 污染：gen_id "6" "project_overview.md" "" "line-N" +``` + +**已 resolved ID 提取**： + +```bash +RESOLVED_IDS=$(grep -B1 "`。 + +**用户如何使用**：在 `lint_report.md` 中某个 NEED-HUMAN 条目末尾、`` 同段内，追加： + +```markdown + +``` + +下次 lint 跑到时，发现该 id 在 `RESOLVED_IDS` 中，整条跳过，不再骚扰。 + +### 报告模板 + +```markdown +--- +name: 记忆健康检查报告 +description: memory-lint 最新一次执行的检查结果与待处理项 +type: lint +last_updated: YYYY-MM-DD +--- + +# 记忆健康检查报告 + +> _执行时间: YYYY-MM-DD | Base commit: `HASH` | Last synced: DATE_ +> +> **如何使用**：NEED-HUMAN 条目末尾有 `` 标记。处理完或决定不处理时，在同段追加 ``，下次 lint 该条目自动跳过。 + +## 健康概览 + +| 检查项 | AUTO-FIX | NEED-HUMAN（含已 resolved 跳过 N 项） | +| --- | --- | --- | +| 1 孤儿 / 2 幽灵 / 3A 引用 / 3B 双链 | N / N / N / N | — / — / N / N | +| 4 矛盾 / 5 过期 / 6 污染 | — | N / N / N | + +**AUTO-FIX 已执行 N 项 | NEED-HUMAN 新列出 N 项 | 历史已 resolved 跳过 M 项** + +--- + +## AUTO-FIX 已执行清单 + +- [x] 移除孤儿：`synthesis_xxx.md` +- [x] 补入幽灵：`feedback_api.md`（feedback） +- [x] 更新断链：`[[feedback.md#旧标题]]` → `[[feedback.md#新标题]]` +- [x] MEMORY.md「引用」列已刷新（N 文件，倒序） + +--- + +## 条目级高频引用 Top（供 memory-update 消费） + +跨 ≥ `SYNTHESIS_THRESHOLD` 个不同源文件被引用的 decisions/feedback 条目。无候选时保留标题 + "无候选"。 + +| 条目 | 跨文件次数 | 建议 | +| --- | --- | --- | +| `decisions.md#示例决策标题` | 4 | 升级为 synthesis_xxx.md | + +--- + +## NEED-HUMAN 待处理清单 + +每项附 3 问 yes/no checklist + 决策矩阵，避免模糊判断，末尾附 ``。 + +### [ERROR] 引用断链 — 目标文件不存在 + +- **位置**：`decisions.md → ## 数据库选型` → `[[synthesis_arch_xxx.md]]` +- **Checklist**：Q1 内容是否真实归档过？Q2 git history 能否找到删除/重命名证据？Q3 该引用是「锦上添花」还是「核心支撑」？ +- **矩阵**：Q1+Q2 是 → 恢复文件；Q1 是 + Q2 否 → 重新归档；Q1 否 → 删引用；Q3 核心 → 必须二选一不允许保留断链 + + +### [WARN] 过期记忆 — 提交速度分级超阈值 + +- **文件**：`project_progress.md`（last_updated: 2026-01-15，过期 86 天，同期 62 次提交，速度 0.72/天 → 中频区 WARN） +- **Checklist**：Q1 覆盖领域在此期间是否有里程碑变更？Q2 现有内容是否仍可指导决策？Q3 是否有继任 synthesis_* 已分担其职责？ +- **矩阵**：Q1 是 + Q2 否 → 触发 memory-update；Q2 是（仅日期老、速度低）→ 仅刷新 last_updated；Q3 是 → 归档/删除，索引指向继任者 + +``` + +## Phase 9 - 输出摘要 + +被 `memory-sync` 调用： + +``` +🔍 memory-lint：AUTO-FIX N 项，NEED-HUMAN N 项（历史 resolved 跳过 M 项，详见 lint_report.md） +``` + +独立调用：扩展输出已修复 / 待处理清单 + 报告路径；全通过则输出「记忆体系健康，已更新执行时间」。 + +发现矛盾候选且 `synonyms.md` 不存在时，额外提示：创建 `.claude/memory/synonyms.md`（或对应的 `.codex/memory/synonyms.md`）可将等价术语预先排除出矛盾检测，降低误报率。 + +每次执行必须更新 `lint_report.md`（即使全通过也刷新执行时间）。 + +## 执行约束 + +1. AUTO-FIX 边界严格 — 只修结构性错误（孤儿、幽灵、断链、双链），不改业务内容。 +2. NEED-HUMAN 完整记录 — 每项含 checklist + 决策矩阵 + 末尾 `` 稳定 ID。 +3. resolved 保活 — Phase 8-pre 提取旧 `lint_report.md` 中带 `` 的 ID 集合，新报告中同 ID 条目跳过；用户标记 resolved 即长效免打扰。 +4. 矛盾检测先过等价表 — 先加载 `synonyms.md` 再判矛盾；措辞不一致 ≠ 矛盾，宁漏报不误报。 +5. 污染检测边界（重申）— 架构层级保留 / 具体类名路径删除。 +6. 使用 `.claude/memory/` 时只复用现有 Claude 项目记忆，不复制到 `.codex/memory/`。 +7. 不访问远程记忆路径，不维护任何跨机器镜像；不 lint Codex 原生 Memories。 +8. 被 `memory-sync` 调用时返回简短摘要；独立调用时输出已修复和待处理清单。 +9. 记忆变更和代码变更分开执行；不要把用户未确认的代码修改混入 lint 修复。 diff --git a/plugins/memcore-codex/skills/memory-lint/agents/openai.yaml b/plugins/memcore-codex/skills/memory-lint/agents/openai.yaml new file mode 100644 index 0000000..85c6e9a --- /dev/null +++ b/plugins/memcore-codex/skills/memory-lint/agents/openai.yaml @@ -0,0 +1,7 @@ +interface: + display_name: "Memory Lint" + short_description: "检查并整理项目记忆健康度" + default_prompt: "Use $memory-lint to check and repair project-local memory health." + +policy: + allow_implicit_invocation: true diff --git a/plugins/memcore-codex/skills/memory-sync/SKILL.md b/plugins/memcore-codex/skills/memory-sync/SKILL.md new file mode 100644 index 0000000..e3ccfc8 --- /dev/null +++ b/plugins/memcore-codex/skills/memory-sync/SKILL.md @@ -0,0 +1,158 @@ +--- +name: memory-sync +description: 编排 Codex 项目本地记忆同步流程：识别现有 CLAUDE.md/.claude/memory，确定唯一记忆目录，执行 memory-update 和 memory-lint，维护项目记忆索引和 AGENTS.md 启动引导。用于完整刷新仓库记忆体系。Codex 版本不使用远程记忆；若已有 Claude 记忆内容则直接引用，不重复添加。 +--- + +# memory-sync + +执行项目本地记忆体系的完整同步周期。会话目录视为 `$PROJECT_DIR`。 + +**前置约束：先 Read `../memcore-shared/SKILL.md`**（记忆目录选择优先级 + 禁止路径 + 常量），其约束在本技能全程生效。 + +## 总流程 + +```text +Phase 0 确定 PROJECT_MEMORY_DIR（按 memcore-shared 优先级） +Phase 1 Git 和记忆冲突检查 +Phase 2 读取现有 Claude/Codex 记忆 +Phase 3 计算 diff 或全量审查范围 +Phase 4 调用 memory-update +Phase 5 调用 memory-lint +Phase 6 维护 AGENTS.md 启动引导 +Phase 7 完成报告 +``` + +## Phase 0 - 确定 PROJECT_MEMORY_DIR + +按 `memcore-shared` 的选择优先级确定 `PROJECT_MEMORY_DIR`。若最终落在「需要创建 `.codex/memory/`」的分支，向用户说明目录结构并等待确认后再继续。 + +## Phase 1 - Git 和记忆冲突检查 + +若项目是 git 仓库，先读取： + +```bash +git status --short +git rev-parse --show-toplevel +git rev-parse --short HEAD +``` + +存在未解决冲突时，优先处理记忆目录内的冲突文件。不要自动提交用户未确认的非记忆变更。 + +非 git 仓库继续执行，commit 字段填 `N/A`。 + +记忆文件冲突采用语义合并，限于 `PROJECT_MEMORY_DIR`： + +| 冲突类型 | 处理方式 | +| --- | --- | +| frontmatter `last_updated` | 取两者较新日期 | +| frontmatter `commit` | 取当前 HEAD 或本地工作区对应值 | +| `## Section` 两边内容相同 | 保留一份 | +| `## Section` 仅一边存在 | 保留或追加到文件末尾 | +| `## Section` 两边都存在但内容不同 | 保留当前本地版本，将另一版本追加为 `## [合并待审] Section`，标注 `` | +| `MEMORY.md` 索引冲突 | 不手工合并，保留当前版本，交给 `memory-lint` 重建索引 | +| `user_profile.md` 或 `synthesis_*.md` | 不自动合并，在文件头标注 `` | + +合并前应备份冲突文件，备份文件不要提交。完成后提示用户审查 `` 标记，并由 `memory-lint` 写入 NEED-HUMAN。 + +## Phase 2 - 读取现有记忆 + +若存在 `MEMORY.md`，先读取索引，再按需加载文件： + +- 必读：`decisions.md`、`feedback*.md`、`project_progress.md`、`project_overview.md` 中由索引标为 project 或 feedback 的文件。 +- 按需：`user_profile.md`、`reference.md`、`synthesis_*.md`、`lint_report.md`。 + +若只有 `CLAUDE.md`，读取其中与项目约定、记忆体系、开发流程有关的章节，并避免重复生成同类内容。 + +## Phase 3 - 计算审查范围 + +从 `MEMORY.md` 头部读取 `Base commit`。有锚点时使用： + +```bash +git diff --name-only $ANCHOR_COMMIT..HEAD +``` + +无锚点、非 git 仓库或首次初始化时执行全量审查。 + +## Phase 4 - 调用 memory-update + +按 `memory-update` 的规则增量写入本地记忆文件和 `MEMORY.md` 索引。 + +要求： + +- 只更新本次变化涉及的维度。 +- 以 Why、约束、边界和协作规范为主。 +- 不记录可从代码直接恢复的明细。 +- 若使用 `.claude/memory/`，保持原目录，不创建重复的 `.codex/memory/`。 + +## Phase 5 - 调用 memory-lint + +按 `memory-lint` 的规则执行健康检查： + +- 修复索引孤儿、幽灵、断链和缺失反向链接。 +- 刷新引用计数。 +- 生成或更新 `lint_report.md`。 +- 将内容矛盾、过期、污染和合并残留写入 NEED-HUMAN。 + +## Phase 6 - 维护 AGENTS.md 启动引导 + +Codex 项目的启动引导优先写入 `AGENTS.md`，避免新会话或上下文压缩后漏读权威项目记忆。 + +处理顺序： + +1. 若项目已有 `AGENTS.md`，检查是否存在 `## 记忆体系（会话启动必读）` 区块。 +2. 若区块存在且仍与 `MEMORY.md` 一致，只引用，不重复追加。 +3. 若区块缺失或过期，先向用户说明将更新的内容，确认后再修改；提取区块内已记录的 commit 锚点（若有），据此判断哪些子章节需要针对性调整，而不是整块重写。 +4. 若项目没有 `AGENTS.md` 但已有 `CLAUDE.md` 或 `.claude/memory/`，默认只引用现有 Claude 记忆；需要 Codex 启动引导时，询问用户是否创建 `AGENTS.md`，不要把 `.claude/memory/` 复制到 `.codex/memory/`。 +5. 若项目没有 `AGENTS.md`、`CLAUDE.md` 和 `.claude/memory/`，需要项目级 Codex 引导时创建 `AGENTS.md`，并指向 `.codex/memory/`。 +6. 不为了 Codex 强制创建或改写 `CLAUDE.md`。 + +`AGENTS.md` 记忆体系区块模板： + +```markdown +## 记忆体系（会话启动必读） + +> 新会话或上下文压缩后，必须先读记忆目录的 `MEMORY.md` 索引，再按需加载文件。代码事实与项目记忆冲突时，以代码事实为准并更新项目记忆。 + +### 读取流程 +1. 读取 `{MEMORY_DIR}/MEMORY.md` 获取文件清单、类型和引用计数。 +2. **必读锚点**：{REQUIRED_MEMORY_FILES} +3. **选读锚点**：{OPTIONAL_MEMORY_FILES} +4. 若仓库使用 `.claude/memory/`，直接读取该目录；不要复制到 `.codex/memory/`。 + +### 权威优先级 +1. 当前代码、配置、测试和真实文件状态。 +2. 仓库内项目记忆：`AGENTS.md`、`CLAUDE.md`、`.claude/memory/` 或 `.codex/memory/`。 +3. Codex 原生 Memories（个人本地召回层，仅作辅助上下文）。 +``` + +区块生成规则： + +- `{MEMORY_DIR}` 必须替换为实际目录：`.claude/memory` 或 `.codex/memory`。 +- `{REQUIRED_MEMORY_FILES}` 必须来自 `MEMORY.md` 中实际存在的 project/feedback 类型文件，通常包括 `decisions.md`、`feedback*.md`、`project_progress.md`、`project_overview.md`。 +- `{OPTIONAL_MEMORY_FILES}` 必须来自 `MEMORY.md` 中实际存在的 user/reference/synthesis/lint 类型文件，通常包括 `user_profile.md`、`reference.md`、`synthesis_*.md`、`lint_report.md`。 +- 已有 `CLAUDE.md` 记忆引导时，`AGENTS.md` 可以指向相同记忆目录，但不要复制正文。 +- 任何写入 `AGENTS.md`、`CLAUDE.md`、`MEMORY.md` 或记忆文件的动作，都必须先说明变更并等待用户确认。 + +## Phase 7 - 完成报告 + +报告包括： + +- 使用的记忆目录。 +- 是否复用了 `CLAUDE.md` 或 `.claude/memory/`。 +- `memory-update` 更新文件数量。 +- `memory-lint` AUTO-FIX 和 NEED-HUMAN 数量（含历史已 `` 跳过的数量）。 +- 高频引用条目候选 synthesis 升级，来自 `lint_report.md` 的「条目级高频引用 Top」；无候选时写明无候选。 +- 是否更新了 `AGENTS.md` 启动引导。 +- 未执行项或跳过项，例如未初始化 `.codex/memory/`、未更新 `AGENTS.md`、存在 NEED-HUMAN 待处理、跳过 synthesis 创建。 +- 当前 `Base commit`。 + +## 执行约束 + +1. 项目本地记忆是唯一来源。 +2. 不访问或模拟 Claude 远程记忆。 +3. 已有 Claude 项目记忆时复用，不复制、不重复生成。 +4. 不读写 Codex 原生 Memories；它们是个人召回层，不是本套项目记忆的后端。 +5. `memory-update` 必须先于 `memory-lint`。 +6. Codex 启动引导优先维护 `AGENTS.md`；不要为了 Codex 强制创建或改写 `CLAUDE.md`。 +7. 修改 `AGENTS.md`、`CLAUDE.md`、`MEMORY.md` 或记忆文件前，先说明变更并取得用户确认。 +8. 记忆变更和代码变更分开执行；不要把用户未确认的代码修改混入记忆同步。 diff --git a/plugins/memcore-codex/skills/memory-sync/agents/openai.yaml b/plugins/memcore-codex/skills/memory-sync/agents/openai.yaml new file mode 100644 index 0000000..b74ef3a --- /dev/null +++ b/plugins/memcore-codex/skills/memory-sync/agents/openai.yaml @@ -0,0 +1,7 @@ +interface: + display_name: "Memory Sync" + short_description: "编排项目本地记忆同步流程" + default_prompt: "Use $memory-sync to synchronize and refresh project-local memory." + +policy: + allow_implicit_invocation: true diff --git a/plugins/memcore-codex/skills/memory-update/SKILL.md b/plugins/memcore-codex/skills/memory-update/SKILL.md new file mode 100644 index 0000000..246afdf --- /dev/null +++ b/plugins/memcore-codex/skills/memory-update/SKILL.md @@ -0,0 +1,199 @@ +--- +name: memory-update +description: 根据 git diff 或当前任务上下文，增量更新仓库/项目本地记忆目录和 MEMORY.md 索引。用于把代码变更、架构决策、协作反馈、外部参考和用户偏好沉淀到项目记忆中。Codex 版本不使用远程记忆；若仓库已有 CLAUDE.md 或 .claude/memory/，直接引用现有 Claude 记忆内容，不重复创建或复制；否则使用 .codex/memory/。 +--- + +# memory-update + +按增量范围更新项目本地记忆。会话目录视为 `$PROJECT_DIR`。 + +**前置约束：先 Read `../memcore-shared/SKILL.md`**（记忆目录选择优先级 + 禁止路径 + 常量），其约束在本技能全程生效。 + +修改 `MEMORY_INDEX` 或任何记忆文件时，优先使用小范围补丁；不要整文件重写。记忆变更和代码变更必须分开说明、分开确认。 + +## Phase 1 - 读取增量锚点 + +```bash +# 主锚点：MEMORY.md 头部 _Last synced: DATE | Base commit: `HASH`_ → $ANCHOR_COMMIT +ANCHOR_COMMIT=$(grep -oE 'Base commit: `[^`]+`' "$PROJECT_MEMORY_DIR/MEMORY.md" 2>/dev/null \ + | head -1 | sed 's/Base commit: `//; s/`$//') + +# 兜底锚点：若 MEMORY.md 头部锚点丢失，取各文件 frontmatter commit 字段的最旧值 +# 防止「误删 MEMORY.md 头部 → 雪崩全量重写」 +if [ -z "$ANCHOR_COMMIT" ] || [ "$ANCHOR_COMMIT" = "N/A" ]; then + FALLBACK=$(grep -h "^commit:" "$PROJECT_MEMORY_DIR/"*.md 2>/dev/null \ + | awk '{print $2}' | sort -u) + if [ -n "$FALLBACK" ]; then + ANCHOR_COMMIT=$(git -C "$PROJECT_DIR" rev-list --topo-order $FALLBACK 2>/dev/null | tail -1) + echo "⚠ MEMORY.md 头部锚点丢失，使用兜底锚点：$ANCHOR_COMMIT（来自各文件 frontmatter 最旧 commit）" + fi +fi + +git -C "$PROJECT_DIR" rev-parse --short HEAD # → $HEAD_HASH（非 git 仓库填 N/A） +``` + +**为什么需要兜底**：`MEMORY.md` 头部的 `Base commit: HASH` 是单一来源，一旦用户手动编辑误删此行，整个 diff 范围会退化为全量，触发 update 重写所有文件。兜底机制从各文件 frontmatter 的 `commit:` 字段取**最旧值**，确保覆盖所有真实改动而不误判为无差别全量。 + +有 `ANCHOR_COMMIT`（含兜底命中）时以该提交作为差量起点；仍为空、非 git 仓库或首次初始化时执行全量审查。 + +## Phase 2 - 计算变更范围 + +```bash +[ -n "$ANCHOR_COMMIT" ] && git diff --name-only $ANCHOR_COMMIT..HEAD # → $CHANGED_FILES +``` + +无锚点时审查当前项目结构、依赖文件、现有记忆文件和本次会话明确产生的信息。 + +## Phase 3 - 更新记忆文件 + +### 维度路由（$CHANGED_FILES → 目标文件） + +| 变更内容 | 写入到 | +| --- | --- | +| 业务代码、模块边界、架构形态 | `project_overview.md`、`decisions.md` | +| 依赖文件、运行方式、工具链 | `project_overview.md` | +| 进度信号、阶段状态、待办 | `project_progress.md` | +| 用户纠正、协作规范、风格偏好 | `feedback.md` 或 `feedback_{topic}.md` | +| 外部 URL、第三方约束 | `reference.md` | +| 用户长期偏好 | `user_profile.md` | +| 高价值分析归档 | `synthesis_{type}_{topic}.md` | + +### 文件职责边界 + +| 文件 | 类型 | 写入 | 不写入 | +| --- | --- | --- | --- | +| `user_profile.md` | user | 角色、背景、长期偏好 | 任务进度 | +| `project_overview.md` | project | 技术栈、架构、目录、约定 | 可从代码直接 grep 的明细 | +| `project_progress.md` | project | 阶段、待办、里程碑 | git 流水账 | +| `decisions.md` | project | Why 格式决策 | 实现细节 | +| `feedback*.md` | feedback | 协作规范，含 Why 和 How to apply | 一次性修复 | +| `reference.md` | reference | 外部 URL 和用途 | 本地路径 | +| `synthesis_*.md` | synthesis | 高价值分析结论 | 对话逐字记录 | + +### 统一 frontmatter + +```markdown +--- +name: 文件标题 +description: 一句话描述，影响未来加载判断 +type: user | project | feedback | reference | synthesis +last_updated: YYYY-MM-DD +commit: HASH +--- +``` + +`type` 可选值包含 `lint`。`memory-update` 通常不生成 `lint_report.md`，但更新索引时必须能识别 `lint` 类型。 + +`decisions.md` 和 `feedback*.md` 条目格式： + +```markdown +## 标题 + +**结论：** xxx +**Why：** 背景、约束、历史教训 +**How to apply：** 何时适用、边界 +**See Also：** [[file.md#标题]] +``` + +`synthesis_*.md` 使用完整文件格式，至少包含 `## 背景`、`## 分析过程`、`## 结论`、`## See Also`。 + +feedback 拆分规则：当同一主题的协作规范超过 5 条，拆分到 `feedback_{topic}.md`，并在原 `feedback.md` 中保留索引或 See Also 引用。一次性修复、临时提醒和已经由代码体现的偏好不要沉淀为 feedback。 + +### Phase 3A - 交叉引用 + +新增 decisions 或 feedback 条目时： + +1. 扫描记忆目录内其他 Markdown 标题。 +2. 主题相关时，在新条目末尾追加 `[[file.md#标题]]`。 +3. 反向补链：被引用条目也追加对新条目的引用。 + +### Phase 3B - synthesis 三路触发 + +当某个 decisions 或 feedback 条目被 `SYNTHESIS_THRESHOLD`（默认 3）个以上不同文件引用，且条目中没有 `**Synthesized:**` 或 30 天内的 `` 标记时，建议升级为 `synthesis_*.md`，并等待用户确认后创建。 + +1. **会话内主动触发**：出现技术选型对比、Bug 根因分析、架构演进、安全或性能分析时，建议归档为 `synthesis_{type}_{topic}.md`。 +2. **lint 反向触发**：读取 `lint_report.md` 的「条目级高频引用 Top」，跨 `SYNTHESIS_THRESHOLD` 个以上不同源文件被引用的 decisions/feedback 条目是候选。 +3. **即时快扫触发**（见 Phase 3C）：每次 update 后扫描 `decisions.md` 和 `feedback*.md` 条目引用数，不等待下一次完整 lint。 + +synthesis 判重和免打扰： + +- 条目已有 `**Synthesized:** [[xxx.md]]` 时，视为已升级，不重复创建。 +- 条目已有 `` 且未超过 30 天时，不再提醒。 +- 用户拒绝单个候选时，在原条目末尾追加 decline 标记。 +- 用户选择 `skip-all` 时，本次 update 不再继续建议 synthesis。 +- 创建 synthesis 后，在原条目末尾追加 `**Synthesized:** [[synthesis_xxx.md]]`。 + +### Phase 3C - 即时引用计数快扫（不依赖 lint） + +每次执行 Phase 3 末尾**强制运行**。目的：在短会话或任务型对话中，不依赖 lint 的延迟触发，直接检测 synthesis 升级候选。 + +```bash +SYNTHESIS_THRESHOLD=3 # 与 memcore-shared 全局常量保持一致 + +for entry_file in "$PROJECT_MEMORY_DIR/decisions.md" "$PROJECT_MEMORY_DIR/feedback"*.md; do + [ -f "$entry_file" ] || continue + fn=$(basename "$entry_file") + while IFS= read -r title; do + # 使用 grep -F（fixed string）避免 [[ ]] 在正则中的歧义；-- 防止 title 以 - 开头被误解为选项 + count=$(grep -rlF -- "[[${fn}#${title}]]" \ + "$PROJECT_MEMORY_DIR/" --include="*.md" 2>/dev/null \ + | grep -v "^${entry_file}$" | wc -l) + [ "$count" -ge "$SYNTHESIS_THRESHOLD" ] && echo "$count|$fn#$title" + done < <(grep "^## " "$entry_file" | sed 's/^## //') +done | sort -t'|' -k1 -rn +``` + +**脚本健壮性说明**： + +- 使用 `grep -F`（fixed string）避免 `[[` `]]` 在正则中的歧义。 +- title 含中文 / 空格 / 标点时不会破坏匹配。 +- 单文件中同标题多次引用按 `-l` 仅记一次（按文件去重）。 + +对每条输出候选（`count|file#title`）： + +1. 读原条目内是否含 `**Synthesized:**` → 已升级，跳过。 +2. 读原条目内是否含 `` → 30 天内，跳过。 +3. 以上均无 → 触发提议（同 Phase 3B step 流程）。 + +**与 lint 的分工**： + +- Phase 3C（快扫）：每次 memory-update 必跑，判据为「存在引用行数」，适合即时触发。 +- lint Phase 3（精扫）：按源文件去重的精确计数，健康检查时运行。 +- 两者以 `**Synthesized:**` 标记为唯一判重依据，不重复创建文件。 +- 阈值唯一来源为 `memcore-shared` 的 `SYNTHESIS_THRESHOLD`，调整请改 `memcore-shared`。 + +### 写入要点 + +- 仅更新有变化维度，不重写无关文件。 +- frontmatter 的 `last_updated` 改今日，`commit` 改 `$HEAD_HASH`。 +- 追加为主，不删已有内容（除非过时/冲突）。 + +## Phase 4 - 更新 MEMORY.md 索引 + +索引格式： + +```markdown +# Memory Index +> _Last synced: YYYY-MM-DD | Base commit: `HASH`_ + +| 文件 | 描述 | 类型 | 引用 | Commit | +| --- | --- | --- | --- | --- | +``` + +更新规则： + +- 改过的文件同步 `Commit` 列。 +- 头部 `Last synced` 和 `Base commit` 改为今日与 `$HEAD_HASH`。 +- 新增文件的 `引用` 列先填 `0`，精确值由 `memory-lint` 刷新。 +- `引用` 值大于等于 `SYNTHESIS_THRESHOLD` 时加 `*`，例如 `5*`。 + +## 执行约束 + +1. 最小化更新，只写本次确认的变化维度。 +2. 不记录可推断内容，例如完整文件路径列表、方法签名、git 流水账。 +3. feedback 同主题超过 5 条时拆分到主题文件。 +4. 追加为主，除非内容明确过时或冲突。 +5. 如果使用的是 `.claude/memory/`，视为复用现有 Claude 项目记忆；不要迁移、复制或生成重复的 `.codex/memory/`。 +6. 不把 Codex 原生 Memories 当作可编辑后端；需要跨会话保留的项目事实必须写入仓库/项目内记忆。 +7. 被 `memory-sync` 调用时只返回简短摘要；独立调用时输出完整更新摘要。 +8. 记忆变更和代码变更分开执行；不要把用户未确认的代码修改混入记忆更新。 diff --git a/plugins/memcore-codex/skills/memory-update/agents/openai.yaml b/plugins/memcore-codex/skills/memory-update/agents/openai.yaml new file mode 100644 index 0000000..47a0107 --- /dev/null +++ b/plugins/memcore-codex/skills/memory-update/agents/openai.yaml @@ -0,0 +1,7 @@ +interface: + display_name: "Memory Update" + short_description: "按变更增量更新项目记忆" + default_prompt: "Use $memory-update to update project-local memory from recent changes." + +policy: + allow_implicit_invocation: true diff --git a/plugins/obsidian/.codex-plugin/plugin.json b/plugins/obsidian/.codex-plugin/plugin.json new file mode 100644 index 0000000..a371273 --- /dev/null +++ b/plugins/obsidian/.codex-plugin/plugin.json @@ -0,0 +1,18 @@ +{ + "name": "obsidian", + "version": "1.0.0", + "description": "Obsidian 知识库 AI 协作插件族。检测到 .obsidian/ 目录时自动激活全套技能：vault 管理、全文搜索与图谱、frontmatter 元数据、Markdown 任务与 GTD、每日笔记、Bases 数据库视图、Canvas 视觉层、版本历史与恢复、插件与环境配置、PKM 编排工作流共 10 个技能。", + "author": { + "name": "姜顺志" + }, + "skills": "./skills", + "interface": { + "displayName": "Obsidian 知识库协作", + "shortDescription": "Obsidian vault 全套协作工作流", + "longDescription": "Obsidian 知识库 AI 协作插件族，检测到项目里的 .obsidian/ 目录后自动激活。覆盖 vault 管理（含 OFM 语法速查）、全文与图谱搜索、frontmatter 元数据、任务与 GTD、每日笔记、Bases 数据库视图、Canvas 视觉层（JSON Canvas 1.0）、版本历史与恢复、插件与环境配置、PKM 编排工作流（含 Web Clip 子流程）十个技能。", + "developerName": "蚁熊团队", + "category": "Productivity", + "capabilities": ["Interactive", "Write"], + "defaultPrompt": "帮我整理一下今天的每日笔记" + } +} diff --git a/plugins/obsidian/skills/obsidian-workflow-pkm/SKILL.md b/plugins/obsidian/skills/obsidian-workflow-pkm/SKILL.md index dd38e13..9beb7de 100644 --- a/plugins/obsidian/skills/obsidian-workflow-pkm/SKILL.md +++ b/plugins/obsidian/skills/obsidian-workflow-pkm/SKILL.md @@ -630,7 +630,7 @@ graph TD | 现象 | 原因 | 对策 | |------|------|------| | 工作流中途失败导致状态不一致 | 没有事务 | 先 git checkpoint；失败后从 checkpoint 恢复 | -| Agent 在决策点没等用户 | 没实现交互 | 脚本用 `read -p`，Claude Code 用 AskUserQuestion | +| Agent 在决策点没等用户 | 没实现交互 | 脚本用 `read -p`，交互式 agent（如 Claude Code 的 AskUserQuestion）用其原生询问机制 | | 批量处理把同一笔记处理两次 | 没用 idempotent 标记 | 处理完在 frontmatter 加 `processed_by: inbox_workflow` | | MOC 构建召回漏掉笔记 | 关键词单一 | 用 3~5 个扩展词 + 标签 + 出/反链三路召回 | | 周报漏数据 | daily note 没写 | 先跑 `obsidian files folder=90-Daily` 检查覆盖 |