yixiong/yixiong-claude-marketplace
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(codex): 新增 Codex CLI 插件市场支持，含独立 memcore-codex

Browse Source 
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 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LVyxoP4cDXeoQ3uAqLcEd2
This commit is contained in:
SkyJourney
2026-08-22 17:13:59 +08:00
co-authored by Claude Sonnet 5
parent afc8e2c7f8
commit 3de9b054ef
18 changed files with 966 additions and 12 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.agents/plugins/marketplace.json
+56
View File
@@ -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"
}
]
}
CHANGELOG.md
+2
View File
@@ -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 生产切换完成后正式首发
README.md
+49 -11
View File
@@ -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)。
plugins/huanxi-admin/.codex-plugin/plugin.json
+19
View File
@@ -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": "帮我看一下本周的汇报盘点情况"
}
}
plugins/huanxi-admin/.mcp.json
+11
View File
@@ -0,0 +1,11 @@
{
"mcpServers": {
"huanxi-admin": {
"type": "http",
"url": "https://huanxi.office.yixiong-tech.com/admin-mcp/",
"headers": {
"Authorization": "Bearer ${HUANXI_ADMIN_TOKEN}"
}
}
}
}
plugins/huanxi/.codex-plugin/plugin.json
+19
View File
@@ -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": "帮我看看今天有哪些任务和待办"
}
}
plugins/huanxi/.mcp.json
+11
View File
@@ -0,0 +1,11 @@
{
"mcpServers": {
"huanxi": {
"type": "http",
"url": "https://huanxi.office.yixiong-tech.com/mcp/",
"headers": {
"Authorization": "Bearer ${HUANXI_TOKEN}"
}
}
}
}
plugins/memcore-codex/.codex-plugin/plugin.json
+18
View File
@@ -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": "帮我同步一下这个项目的本地记忆"
}
}
plugins/memcore-codex/skills/memcore-shared/SKILL.md
+74
View File
@@ -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-warn: N -->` 覆盖 `LINT_STALE_MIN_DAYS`。
---
## 引用约定
子技能开头标准引用句：
```markdown
**前置约束：先 Read `../memcore-shared/SKILL.md`（记忆目录选择优先级 + 禁止路径 + 常量）**
```
读取后，子技能内所有出现的 `$PROJECT_DIR`、`PROJECT_MEMORY_DIR`、`MEMORY_INDEX`、`SESSION_GUIDE_FILE` 及上述常量均按本文件定义执行。
plugins/memcore-codex/skills/memcore-shared/agents/openai.yaml
+6
View File
@@ -0,0 +1,6 @@
interface:
display_name: "Memcore Shared"
short_description: "memcore 内部共享约定（不直接调用）"
policy:
allow_implicit_invocation: false
plugins/memcore-codex/skills/memory-lint/SKILL.md
+304
View File
@@ -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 | 归档结论是否抵触现有决策 |
| 合并残留标记 | 是否含 `<!-- merge-conflict -->` |
矛盾判定门槛（过 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-warn: N -->` 覆盖 `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 条目添加 `<!-- resolved -->` 标记后，下次 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 "<!-- resolved" "$PROJECT_MEMORY_DIR/lint_report.md" 2>/dev/null \
| grep -oE '<!-- id: [a-f0-9]{8}' | awk '{print $3}')
```
**生成新 NEED-HUMAN 时的过滤**：对每个新检测出的 NEED-HUMAN 条目，计算 `id = gen_id(phase, file, section, fact)`；若 `id` 在 `RESOLVED_IDS` 中则跳过（用户已标记 resolved，本次不再列出）；否则写入 `lint_report.md`，并在条目末尾附 `<!-- id: {id} -->`。
**用户如何使用**：在 `lint_report.md` 中某个 NEED-HUMAN 条目末尾、`<!-- id: ... -->` 同段内，追加：
```markdown
<!-- resolved: 2026-06-12, 决定保留两者作为历史对比 -->
```
下次 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 条目末尾有 `<!-- id: xxxxxxxx -->` 标记。处理完或决定不处理时，在同段追加 `<!-- resolved: DATE, 简要原因 -->`，下次 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 + 决策矩阵，避免模糊判断，末尾附 `<!-- id: xxxxxxxx -->`。
### [ERROR] 引用断链 — 目标文件不存在
- **位置**：`decisions.md → ## 数据库选型` → `[[synthesis_arch_xxx.md]]`
- **Checklist**：Q1 内容是否真实归档过？Q2 git history 能否找到删除/重命名证据？Q3 该引用是「锦上添花」还是「核心支撑」？
- **矩阵**：Q1+Q2 是 → 恢复文件；Q1 是 + Q2 否 → 重新归档；Q1 否 → 删引用；Q3 核心 → 必须二选一不允许保留断链
<!-- id: a1b2c3d4 -->
### [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 是 → 归档/删除，索引指向继任者
<!-- id: c9d0e1f2 -->
```
## 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: xxxxxxxx -->` 稳定 ID。
3. resolved 保活 — Phase 8-pre 提取旧 `lint_report.md` 中带 `<!-- resolved -->` 的 ID 集合，新报告中同 ID 条目跳过；用户标记 resolved 即长效免打扰。
4. 矛盾检测先过等价表 — 先加载 `synonyms.md` 再判矛盾；措辞不一致 ≠ 矛盾，宁漏报不误报。
5. 污染检测边界（重申）— 架构层级保留 / 具体类名路径删除。
6. 使用 `.claude/memory/` 时只复用现有 Claude 项目记忆，不复制到 `.codex/memory/`。
7. 不访问远程记忆路径，不维护任何跨机器镜像；不 lint Codex 原生 Memories。
8. 被 `memory-sync` 调用时返回简短摘要；独立调用时输出已修复和待处理清单。
9. 记忆变更和代码变更分开执行；不要把用户未确认的代码修改混入 lint 修复。
plugins/memcore-codex/skills/memory-lint/agents/openai.yaml
+7
View File
@@ -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
plugins/memcore-codex/skills/memory-sync/SKILL.md
+158
View File
@@ -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`，标注 `<!-- merge-conflict: YYYY-MM-DD -->` |
| `MEMORY.md` 索引冲突 | 不手工合并，保留当前版本，交给 `memory-lint` 重建索引 |
| `user_profile.md` 或 `synthesis_*.md` | 不自动合并，在文件头标注 `<!-- merge-conflict: YYYY-MM-DD, NEED-HUMAN -->` |
合并前应备份冲突文件，备份文件不要提交。完成后提示用户审查 `<!-- merge-conflict -->` 标记，并由 `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 数量（含历史已 `<!-- resolved -->` 跳过的数量）。
- 高频引用条目候选 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. 记忆变更和代码变更分开执行；不要把用户未确认的代码修改混入记忆同步。
plugins/memcore-codex/skills/memory-sync/agents/openai.yaml
+7
View File
@@ -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
plugins/memcore-codex/skills/memory-update/SKILL.md
+199
View File
@@ -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-decline: YYYY-MM-DD -->` 标记时，建议升级为 `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]]` 时，视为已升级，不重复创建。
- 条目已有 `<!-- synthesis-decline: YYYY-MM-DD -->` 且未超过 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. 读原条目内是否含 `<!-- synthesis-decline: YYYY-MM-DD -->` → 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. 记忆变更和代码变更分开执行；不要把用户未确认的代码修改混入记忆更新。
plugins/memcore-codex/skills/memory-update/agents/openai.yaml
+7
View File
@@ -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
plugins/obsidian/.codex-plugin/plugin.json
+18
View File
@@ -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": "帮我整理一下今天的每日笔记"
}
}
plugins/obsidian/skills/obsidian-workflow-pkm/SKILL.md
+1 -1
View File
@@ -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` 检查覆盖 |