chore: memory-sync — 归档 memcore-shared/lint_report 保活/Base commit 兜底等决策
- decisions.md 新增 3 项：memcore-shared 共享层、lint_report 增量保活、Phase 1 锚点兜底 - feedback_plugin_dev.md 新增 2 项：skill 不重写 MCP 参数表、签名变更全量扫描 - project_overview.md：memcore 技能数 3→4，新增 memcore-shared - AUTO-FIX：feedback#skill-不重写MCP参数表 补反向引用至 decisions - 引用列：decisions/project_overview/feedback 均为 1，lint_report 为 0 - CLAUDE.md 元数据更新（commit 38beecb），引导区块刷新 Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This commit is contained in:
SkyJourney
co-authored by
Claude Opus 4.7
Claude Opus 4.7
parent
38beecb2d0
commit
a9a89e57c3
@@ -1,9 +1,9 @@
|
||||
# Memory Index
|
||||
> _Last synced: 2026-05-10 | Base commit: `f26e741`_
|
||||
> _Last synced: 2026-06-12 | Base commit: `38beecb`_
|
||||
|
||||
| 文件 | 描述 | 类型 | 引用 | Commit |
|
||||
|------|------|------|------|--------|
|
||||
| decisions.md | 关键架构决策：无版本号/userConfig/Bearer Token/SKILL.md规范/路径锁定/memcore三项优化决策 | project | 1 | f26e741 |
|
||||
| project_overview.md | 项目定位、目录结构、插件规范、发布流程（huanxi/memcore/obsidian） | project | 1 | f26e741 |
|
||||
| feedback_plugin_dev.md | 插件开发协作规范：同步四处/路径解析/工具签名对照 | feedback | 0 | 0c46ed0 |
|
||||
| lint_report.md | memory-lint 最新执行结果 | lint | 0 | 0c46ed0 |
|
||||
| decisions.md | 关键架构决策：无版本号/userConfig/Bearer Token/SKILL.md规范/路径锁定/memcore三项优化/memcore-shared共享层/lint_report保活/Base commit兜底 | project | 1 | 38beecb |
|
||||
| project_overview.md | 项目定位、目录结构、插件规范、发布流程（huanxi/memcore/obsidian） | project | 1 | 38beecb |
|
||||
| feedback_plugin_dev.md | 插件开发协作规范：同步四处/路径解析/工具签名对照/MCP docstring单一真相/签名变更全量扫描 | feedback | 1 | 38beecb |
|
||||
| lint_report.md | memory-lint 最新执行结果 | lint | 0 | 38beecb |
|
||||
|
||||
@@ -2,8 +2,8 @@
|
||||
name: 架构决策
|
||||
description: Marketplace 设计中的关键技术决策及其原因
|
||||
type: project
|
||||
last_updated: 2026-05-10
|
||||
commit: f26e741
|
||||
last_updated: 2026-06-12
|
||||
commit: 38beecb
|
||||
---
|
||||
|
||||
# 关键架构决策
|
||||
@@ -95,6 +95,40 @@ commit: f26e741
|
||||
|
||||
---
|
||||
|
||||
## memcore-shared：路径锁定 + 全局常量的单一来源
|
||||
|
||||
**结论**：把路径锁定、全局常量（SYNTHESIS_THRESHOLD / LINT_STALE_*_DAYS / MULTI_HOST_WARN_DAYS）、PROJECT_DIR 跨平台解析提取到独立 skill `memcore-shared`，三个主技能（memory-sync / memory-update / memory-lint）开头 `Read ../memcore-shared/SKILL.md` 引用其约束。description 中显式说明"内部 include，不由用户直接调用"。
|
||||
|
||||
**Why**：原设计中 memory-update 和 memory-lint 各自维护一份 20 行的"路径锁定"块，完全重复；阈值常量 `≥3`、`≥30/90 天`、`≥7 天` 分散硬编码在多个文件多个位置，调整需多处改动。共享层独立成 skill 后：① 单点维护、② 阈值修改只动一处、③ 与 huanxi-shared 同模式，可演进性强。
|
||||
|
||||
**How to apply**：未来 memcore 类多 skill 插件如出现「共享约束 + 多处硬编码常量」时，提取为独立 `<plugin>-shared` skill；常量声明在共享 skill 顶部表格，子技能引用常量名而非裸数字。
|
||||
|
||||
**See Also**：[[decisions.md#memcore memory-update/lint 路径锁定：禁止写入系统自动记忆路径]] [[feedback_plugin_dev.md#skill 不要重写 MCP 参数表，引用 docstring]]
|
||||
|
||||
---
|
||||
|
||||
## memcore lint_report 增量保活：稳定 ID + resolved 跳过
|
||||
|
||||
**结论**：lint Phase 8 生成 NEED-HUMAN 条目时，末尾附 `<!-- id: 8位sha1 -->`（基于 phase + 文件 + 章节 + 关键事实计算）。Phase 8-pre 提取旧 `lint_report.md` 中带 `<!-- resolved -->` 标记的 ID 集合，新报告中同 ID 条目跳过。
|
||||
|
||||
**Why**：原 lint_report.md 每次覆盖写入，用户即使在 NEED-HUMAN 条目处理完或决定"不处理"后，下次 lint 仍会重新列出。导致信号疲劳，长期看反而忽视所有 lint 提示。引入稳定 ID + resolved 标记后，用户对每个条目的判断（处理/接受现状）能跨多次 lint 持续生效，lint_report 变成只列"真正待处理"的事项。
|
||||
|
||||
**How to apply**：任何"周期性扫描 + 报告生成"的 lint/check 系统，凡有用户主观判断维度（不只是机器判定）时，输出条目都应有稳定 ID + 用户标记跳过机制。ID 计算用「问题本体」字段（位置+事实），不要包含执行时间/扫描序号。
|
||||
|
||||
---
|
||||
|
||||
## memory-update Phase 1 锚点丢失兜底
|
||||
|
||||
**结论**：memory-update Phase 1 读 `Base commit` 锚点时，若 MEMORY.md 头部该行缺失或为 N/A，从各 memory 文件 frontmatter 的 `commit:` 字段取最旧值兜底，避免退化为全量。
|
||||
|
||||
**Why**：MEMORY.md 头部 `Base commit: HASH` 是单一锚点来源，一旦用户手动编辑误删此行，整个 git diff 范围退化为全量审查，触发 memory-update 对所有文件做"按变更维度重写"。即使大部分文件没真实变化，也会被刷一次 last_updated 和 commit 字段，造成虚假改动。兜底机制从各文件 frontmatter 取最旧 commit，确保覆盖所有真实差量而非无差别全量。
|
||||
|
||||
**How to apply**：任何"单点配置 → 关键路径"的设计，必须考虑配置丢失时的退路。优先级：单点 → 多点冗余 → 兜底推导。memcore 当前是「单点 + 兜底推导」，无需冗余存储。
|
||||
|
||||
**See Also**：[[decisions.md#memcore memory-sync：冲突检测必须先于 git commit]]
|
||||
|
||||
---
|
||||
|
||||
## SKILL.md frontmatter 只保留 name 和 description
|
||||
|
||||
**结论**：SKILL.md frontmatter 只写 `name` 和 `description` 两个字段，去掉 `version`。
|
||||
|
||||
@@ -2,8 +2,8 @@
|
||||
name: 插件开发协作反馈
|
||||
description: 在此 marketplace 项目中开发插件时需遵守的协作规范和经验教训
|
||||
type: feedback
|
||||
last_updated: 2026-05-01
|
||||
commit: 0c46ed0
|
||||
last_updated: 2026-06-12
|
||||
commit: 38beecb
|
||||
---
|
||||
|
||||
# 插件开发协作规范
|
||||
@@ -55,3 +55,33 @@ commit: 0c46ed0
|
||||
**Why**：本次发现 huanxi-shared 工具索引中 report_submit/withdraw 用了旧名，leader_report_submit/withdraw 缺必填参数，weekly_report_save 参数名用 week 而非 week_number，这些都是 MCP 升级后 skill 未同步导致的。
|
||||
|
||||
**How to apply**：每次 MCP server 工具链升级后，运行 plugin-validator 对照检查 skill 中的工具调用。
|
||||
|
||||
---
|
||||
|
||||
## skill 不要重写 MCP 参数表，引用 docstring 为单一真相
|
||||
|
||||
**规范**：MCP 工具的参数细节（字段名、必填、枚举值、类型）以后端 Python 函数 docstring 为**单一真相来源**。skill 文档不要重画完整字段表，最多给一个 happy path 的调用示例 + 历史踩坑说明，在 reference 文档顶部统一声明"参数细节以 MCP `<tool_name>` 的 docstring 为准"。
|
||||
|
||||
**Why**：本次发现 `huanxi-report/references/report-draft.md` 的字段表与后端 `report_save_draft` docstring 大幅漂移（缺 module_id 必填、progress 字段名错为 progress 应为 progress_update、虚构 status 字段），直接导致用户日报频繁报"参数缺失"。skill 一旦重画参数表，就和 MCP docstring 形成两套真相 —— 任一处改动另一处就漂移。同类漂移在 weekly（week→week_number）、task（due_date→end_date / urgent→critical / todo→not_started）、org（user_id→id）系列均出现，呈系统性问题。
|
||||
|
||||
**How to apply**：
|
||||
1. 写 skill 时不画字段表；如非要列字段，必须在文末加"以 MCP docstring 为准"声明
|
||||
2. 给 LLM 的提示是"调 MCP 时直接信任 docstring"而非"按本文档调用"
|
||||
3. MCP 工具签名变更时**不需要**改 skill（只要 skill 没硬编码参数表）
|
||||
|
||||
**See Also**：[[feedback_plugin_dev.md#plugin-validator 和 skill-reviewer 审查之后要对照实际代码修正工具签名]] [[feedback_plugin_dev.md#MCP 后端工具签名变更后必须全量扫描所有 skill]] [[decisions.md#memcore-shared：路径锁定 + 全局常量的单一来源]]
|
||||
|
||||
---
|
||||
|
||||
## MCP 后端工具签名变更后必须全量扫描所有 skill
|
||||
|
||||
**规范**：MCP server 的工具签名（参数名、必填项、枚举值、返回字段）变更后，必须对引用该 MCP 的所有 skill 做全量 grep 扫描，找到漂移点逐一对齐。不要依赖单元测试或调用时报错来"被动发现"。
|
||||
|
||||
**Why**：本次扫描发现 huanxi 的 6 个 skill + 7 个 reference 中漂移密度极高：4 类典型模式（字段名错 / 枚举值错 / 缺必填 / 缓存示例与后端返回结构不一致）覆盖所有 huanxi-* 系列。漂移源于后端 docstring 在多次迭代中演进，但 skill 未同步审查。这种漂移在调用时才会被发现（"参数缺失"、"字段不存在"），对用户体验是慢性损耗。
|
||||
|
||||
**How to apply**：
|
||||
1. 后端 PR 中涉及 MCP 工具的，PR 描述必须列出签名变更点
|
||||
2. 合并后立即在 marketplace 仓库做对照扫描（grep 漂移关键词，如旧字段名）
|
||||
3. 漂移修正与签名变更在同一 sprint 完成，不留尾巴
|
||||
|
||||
**典型扫描点**（针对 huanxi）：参数名 `progress` vs `progress_update`、`due_date` vs `end_date`、`week` vs `week_number`；枚举值 `todo` vs `not_started`、`urgent` vs `critical`；返回字段 `user_id` vs `id`。
|
||||
|
||||
@@ -2,38 +2,59 @@
|
||||
name: 记忆健康检查报告
|
||||
description: memory-lint 最新一次执行的检查结果与待处理项
|
||||
type: lint
|
||||
last_updated: 2026-05-10
|
||||
last_updated: 2026-06-12
|
||||
commit: 38beecb
|
||||
---
|
||||
|
||||
# 记忆健康检查报告
|
||||
|
||||
> _执行时间: 2026-05-10 | Base commit: `f26e741` | Last synced: 2026-05-10_
|
||||
> _执行时间: 2026-06-12 | Base commit: `38beecb` | Last synced: 2026-06-12_
|
||||
>
|
||||
> **如何使用**：NEED-HUMAN 条目末尾有 `<!-- id: xxxxxxxx -->` 标记。处理完或决定不处理时，在同段追加 `<!-- resolved: DATE, 简要原因 -->`，下次 lint 该条目自动跳过。
|
||||
|
||||
## 健康概览
|
||||
|
||||
| 检查项 | AUTO-FIX | NEED-HUMAN |
|
||||
|--------|---------|-----------|
|
||||
| 1 孤儿 / 2 幽灵 / 3A 引用 / 3B 双链 | 0 / 0 / 0 / 0 | — / — / 0 / 0 |
|
||||
| 1 孤儿 / 2 幽灵 / 3A 引用 / 3B 双链 | 0 / 0 / 0 / 1 | — / — / 0 / 0 |
|
||||
| 4 矛盾 / 5 过期 / 6 污染 | — | 0 / 0 / 0 |
|
||||
|
||||
**AUTO-FIX 已执行 0 项 | NEED-HUMAN 待处理 0 项**
|
||||
**AUTO-FIX 已执行 1 项 | NEED-HUMAN 新列出 0 项 | 历史已 resolved 跳过 0 项**
|
||||
|
||||
---
|
||||
|
||||
## AUTO-FIX 已执行清单
|
||||
|
||||
无
|
||||
- [x] 双链补全（Phase 3B）：`feedback_plugin_dev.md#skill 不要重写 MCP 参数表，引用 docstring` 末尾追加对 `[[decisions.md#memcore-shared：路径锁定 + 全局常量的单一来源]]` 的反向引用
|
||||
- [x] MEMORY.md「引用」列已刷新（4 文件）
|
||||
|
||||
---
|
||||
|
||||
## 条目级高频引用 Top（供 /memory-update 消费）
|
||||
|
||||
无候选（所有条目跨文件引用次数 < 3）
|
||||
跨 ≥`SYNTHESIS_THRESHOLD`（默认 3）个不同源文件被引用的 decisions/feedback 条目。
|
||||
|
||||
| 条目 | 跨文件次数 | 建议 |
|
||||
|------|----------|------|
|
||||
| — | — | 无候选 |
|
||||
|
||||
当前所有 decisions/feedback 条目的跨文件引用数均 < 3，无 synthesis 升级候选。
|
||||
|
||||
---
|
||||
|
||||
## NEED-HUMAN 待处理清单
|
||||
|
||||
✅ 全部通过，无待处理项。
|
||||
✅ 本次扫描无 NEED-HUMAN 待处理项，记忆体系健康。
|
||||
|
||||
**备注**：`synonyms.md` 不存在，矛盾检测使用保守模式（仅检测直接数值/版本冲突）。如项目有领域术语缩写，建议创建 `.claude/memory/synonyms.md`。
|
||||
**备注**：`synonyms.md` 不存在，矛盾检测使用保守模式（仅检测直接数值/版本冲突）。如项目有领域术语缩写，建议创建 `.claude/memory/synonyms.md`（首次创建后会被 Phase 2 自动登记为 reference 类型入索引）。
|
||||
|
||||
---
|
||||
|
||||
## 文件级引用计数（来自 Phase 3A，按源文件去重）
|
||||
|
||||
| 文件 | 被引用次数（去重源） | 引用来源 |
|
||||
|------|-------|---------|
|
||||
| project_overview.md | 1 | decisions.md（2 个章节，同一源文件去重为 1） |
|
||||
| decisions.md | 1 | project_overview.md |
|
||||
| feedback_plugin_dev.md | 1 | decisions.md |
|
||||
| lint_report.md | 0 | — |
|
||||
|
||||
@@ -2,8 +2,8 @@
|
||||
name: 项目概述
|
||||
description: yixiong-claude-marketplace 的定位、目录结构、插件规范和发布流程
|
||||
type: project
|
||||
last_updated: 2026-05-10
|
||||
commit: f26e741
|
||||
last_updated: 2026-06-12
|
||||
commit: 38beecb
|
||||
---
|
||||
|
||||
# 蚁熊内部 Claude Code Marketplace
|
||||
@@ -60,8 +60,8 @@ description: "触发描述（用户实际口语，不用内部视角）"
|
||||
|
||||
| 插件 | 技能 | 特性 |
|
||||
|------|------|------|
|
||||
| `huanxi` | 6 个（report/leader/task/weekly/org/shared） | userConfig Bearer Token + MCP Server |
|
||||
| `memcore` | 3 个（memory-sync/lint/update） | 纯技能，无 MCP；支持 synonyms.md 等价词表、Phase 3C 即时引用快扫、Phase 0 并发冲突保护 |
|
||||
| `huanxi` | 6 个（report/leader/task/weekly/org/shared） | userConfig Bearer Token + MCP Server（URL 走 office 子域，无端口） |
|
||||
| `memcore` | 4 个（memory-sync/lint/update/shared） | 纯技能，无 MCP；memcore-shared 作内部 include（路径锁定 + 阈值常量 + PROJECT_DIR 解析），支持 synonyms.md 等价词表、Phase 3C 即时引用快扫、Phase 0 并发冲突保护、lint_report 稳定 ID + resolved 跳过、Base commit 兜底 |
|
||||
| `obsidian` | 9 个（obsidian/bases/daily/history/meta/plugins/search/tasks/workflow-pkm） | 纯技能，无 MCP |
|
||||
|
||||
**See Also**：[[decisions.md#huanxi plugin 使用 userConfig 而非环境变量传 Token]]
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
<!-- Last updated: 2026-05-08 | Commit: 9c91382 -->
|
||||
<!-- Last updated: 2026-06-12 | Commit: 38beecb -->
|
||||
# CLAUDE.md
|
||||
|
||||
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
||||
@@ -103,17 +103,17 @@ description: 一句话说明该技能的用途（Claude 用此判断何时触发
|
||||
### 读取流程
|
||||
|
||||
1. `cat .claude/memory/MEMORY.md` 获取清单
|
||||
2. **必读**（type=`project`/`feedback`）：decisions.md / feedback_plugin_dev.md / project_overview.md
|
||||
3. **按需**（type=`lint`）：lint_report.md
|
||||
2. **必读**（type=`project`/`feedback`）：decisions.md / project_overview.md / feedback_plugin_dev.md
|
||||
3. **按需**（type=`lint`）：lint_report.md（仅查看 NEED-HUMAN 待处理项时读）
|
||||
|
||||
### 记忆目录骨架
|
||||
|
||||
```
|
||||
.claude/memory/
|
||||
├── MEMORY.md # 索引（入口）
|
||||
├── decisions.md # 关键架构决策
|
||||
├── project_overview.md # 项目定位与结构
|
||||
├── feedback_plugin_dev.md # 插件开发协作规范
|
||||
├── decisions.md # 关键架构决策（含 memcore-shared/lint_report 保活/Base commit 兜底等 11 项）
|
||||
├── project_overview.md # 项目定位与结构（huanxi/memcore/obsidian 已发布插件）
|
||||
├── feedback_plugin_dev.md # 插件开发协作规范（含 MCP docstring 单一真相、签名变更全量扫描）
|
||||
└── lint_report.md # 记忆健康检查报告（按需）
|
||||
```
|
||||
|
||||
|
||||
Reference in New Issue
Block a user