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

chore: sync before memory update

Browse Source
This commit is contained in:
SkyJourney
2026-05-01 12:04:12 +08:00
parent 1b3ae007ee
commit 0c46ed0306
22 changed files with 1850 additions and 20 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.claude-plugin/marketplace.json
+10 -5
View File
@@ -1,14 +1,19 @@
{
"name": "yixiong-tools",
"name": "yixiong-claude-hub",
"owner": {
"name": "蚁熊团队"
},
"description": "蚁熊公司内部 Claude Code 技能市场",
"description": "蚁熊官方出品的 Claude Code 能力增强平台。这里汇聚了团队在工程实践中沉淀的精选技能与工作流插件——从代码审查到数据工程，从项目管理到 AI 辅助写作，每一个插件都源自真实业务场景的打磨。装上它，让 Claude Code 更懂蚁熊。",
"plugins": [
{
"name": "example-skill",
"source": "./plugins/example-skill",
"description": "示例插件，演示 Plugin 结构"
"name": "huanxi",
"source": "./plugins/huanxi",
"description": "寰汐企业管理系统插件：日报/负责人日报/周报/任务管理/组织查询，含 MCP Server 自动配置（Bearer Token 直连）"
},
{
"name": "memcore",
"source": "./plugins/memcore",
"description": "记忆体系核心引擎：memory-sync（全量同步）、memory-update（增量写入）、memory-lint（健康校验）"
}
]
}
CLAUDE.md
+87
View File
@@ -0,0 +1,87 @@
# CLAUDE.md
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
## 项目概述
蚁熊公司内部 Claude Code Plugin Marketplace（技能市场）。开发者在此仓库中维护供全员安装使用的 Claude Code 插件（Plugin）和技能（Skill）。
## 目录结构
```
.claude-plugin/
└── marketplace.json # 市场索引：声明本仓库包含哪些插件
plugins/
└── <plugin-name>/ # 每个插件独占一个子目录
├── .claude-plugin/
│ └── plugin.json # 插件元数据（name, description, version, author）
└── skills/
└── <skill-name>/
└── SKILL.md # 技能实现（frontmatter + Markdown 指令）
```
## 核心文件格式
### marketplace.json（市场索引）
```json
{
"name": "yixiong-claude-hub",
"owner": { "name": "蚁熊团队" },
"description": "...",
"plugins": [
{ "name": "<plugin-name>", "source": "./plugins/<plugin-name>", "description": "..." }
]
}
```
每新增一个插件，必须在 `plugins` 数组中追加对应条目。
### plugin.json（插件元数据）
```json
{
"name": "plugin-name",
"description": "...",
"version": "1.0.0",
"author": { "name": "蚁熊团队" }
}
```
版本遵循 SemVer：修改技能内容 → patch，新增技能 → minor，破坏性变更 → major。
### SKILL.md（技能实现）
```markdown
---
description: 一句话说明该技能的用途（Claude 用此判断何时触发该技能）
---
技能的具体指令内容…
```
`description` 字段是触发判据，务必精确描述使用场景，避免与其他技能产生歧义。
## 新增插件流程
1. 在 `plugins/` 下创建目录 `plugins/<plugin-name>/`
2. 创建 `plugins/<plugin-name>/.claude-plugin/plugin.json`
3. 在 `plugins/<plugin-name>/skills/<skill-name>/SKILL.md` 编写技能
4. 在 `.claude-plugin/marketplace.json` 的 `plugins` 数组中追加该插件条目
## 已发布插件
| 插件 | 技能 | 说明 |
|------|------|------|
| `huanxi` | `/huanxi-shared` `/huanxi-report` `/huanxi-leader` `/huanxi-task` `/huanxi-weekly` `/huanxi-org` | 寰汐企业管理系统完整工作流，含 MCP Server 自动配置 |
| `memcore` | `/memory-sync` `/memory-update` `/memory-lint` | 项目记忆体系核心引擎 |
### memcore 技能调用关系
```
/memory-sync ← 总编排（11 phases），调用下面两个技能
├── /memory-update ← 增量写入，可独立执行
└── /memory-lint ← 健康校验，可独立执行
```
plugins/example-skill/.claude-plugin/plugin.json
-8
View File
@@ -1,8 +0,0 @@
{
"name": "example-skill",
"description": "示例插件",
"version": "1.0.0",
"author": {
"name": "蚁熊团队"
}
}
plugins/example-skill/skills/example/SKILL.md
-7
View File
@@ -1,7 +0,0 @@
---
description: 示例技能，用于验证 marketplace 安装流程是否正常
---
这是一个示例技能。当你成功安装并调用它时，说明你的公司内部 marketplace 已经配置成功。
请回复：marketplace 安装验证通过！
plugins/huanxi/.claude-plugin/plugin.json
+24
View File
@@ -0,0 +1,24 @@
{
"name": "huanxi",
"description": "寰汐企业管理系统 Claude Code 插件。集成日报、负责人日报、周报、任务管理、组织查询六大工作流技能，并自动配置寰汐 MCP Server 连接（Bearer Token 直连模式）。",
"author": {
"name": "蚁熊团队"
},
"userConfig": {
"token": {
"type": "string",
"title": "寰汐 Personal Token",
"description": "在寰汐系统后台「设置 → Personal Token」生成，hxp_ 前缀",
"sensitive": true
}
},
"mcpServers": {
"huanxi": {
"type": "http",
"url": "https://pm.yixiong.com/mcp/",
"headers": {
"Authorization": "Bearer ${user_config.token}"
}
}
}
}
plugins/huanxi/skills/huanxi-leader/SKILL.md
+99
View File
@@ -0,0 +1,99 @@
---
name: huanxi-leader
description: "寰汐负责人日报工作流：查看下属汇报情况（+check）、AI 生成并保存草稿（+draft）、提交负责人日报（+submit）、撤回（+withdraw）。当用户说"查看下属汇报"、"写负责人日报"、"汇总下属情况"、"负责人日报"时触发。"
---
# 寰汐负责人日报
**前置条件：先 Read `../huanxi-shared/SKILL.md`（缓存规则 + TTL 策略）**
---
## 标准工作流（完整流程）
```
Step 0: 确认身份和负责的模块
→ Read ~/.claude/huanxi-cache/me.json（永久缓存）
→ Read ~/.claude/huanxi-cache/modules.json（24h 缓存）
→ 筛选 my_role == 'leader' 的模块
→ 若有多个 leader 模块，询问用户选择哪个（或所有）
Step 1: 获取并展示下属汇报汇总
→ 单模块：mcp__huanxi__leader_report_get_subordinates(date=今日, module_id)
→ 多模块：mcp__huanxi__leader_report_get_batch(date=今日, module_ids=[...])
再按模块逐一展示
→ 展示结构化汇总：
✅ 已提交（N人）：[姓名] + 汇报内容摘要
⏳ 未提交（M人）：[姓名]
→ 若有未提交成员：告知用户（供参考，不强制等待）
Step 2: 询问是否 AI 汇总
→ 展示已提交成员的汇报内容后，询问：
"是否需要 AI 根据以上下属汇报自动生成今日负责人日报？"
→ 用户同意 → mcp__huanxi__llm_generate_leader_summary(module_id, date=今日)
→ 展示 AI 生成的汇总报告，供用户审阅和修改
→ 用户拒绝 → 引导用户手动填写报告内容
Step 3: 保存草稿
→ 详见 references/leader-summary.md
→ mcp__huanxi__leader_report_save(report_date, content=<确认后内容>, module_id)
Step 4: 确认并提交
→ 展示最终内容，等待用户明确确认（"确认"/"提交"/"好的"等）
→ ⚠️ 未收到确认前，禁止调用 leader_report_submit
→ mcp__huanxi__leader_report_submit(report_date, module_id)
```
---
## Shortcuts
| 指令 | 说明 |
|------|------|
| `+check` | 查看指定日期下属提交情况 |
| [`+draft`](references/leader-summary.md) | AI 生成草稿并保存（需用户确认内容） |
| `+submit` | 提交负责人日报（必须先确认） |
| `+withdraw` | 撤回已提交负责人日报 |
---
## +check：查看下属汇报
```
1. 确定模块（从 modules.json 缓存中取 leader 身份的模块）
2. mcp__huanxi__leader_report_get_subordinates(date, module_id)
3. 展示：
✅ 已提交（N人）：张三、李四、...
⏳ 未提交（M人）：王五、...
（非工作日时：提示"今日非工作日，成员无需强制提交"）
```
---
## +withdraw：撤回负责人日报
```
1. 确认当前已提交状态
2. 告知撤回影响，等待用户确认
3. mcp__huanxi__leader_report_withdraw(report_date, module_id)
```
---
## 多模块处理
若用户有多个 leader 模块：
```
- 默认展示全部模块的下属情况（+check）
- 提交时需逐模块操作：每个模块单独调用 leader_report_save + submit
- 可用 leader_report_get_batch(date, module_ids) 批量拉取数据
```
---
## 关键约束
- **禁止自动提交**：`leader_report_submit(report_date, module_id)` 前必须展示内容并等待用户确认
- **成员未提交不阻塞**：负责人日报不依赖所有成员提交，可随时填写
- 若当前用户不是任何模块的 leader，告知用户并建议使用 `/huanxi-report` 填写员工日报
plugins/huanxi/skills/huanxi-leader/references/leader-summary.md
+74
View File
@@ -0,0 +1,74 @@
# 负责人日报草稿（+draft）
## 两种草稿模式
### 模式 A：AI 自动生成
```
1. mcp__huanxi__llm_generate_leader_summary(module_id=<模块ID>, date=<日期>)
2. 展示 AI 生成的草稿内容给用户审阅
3. 询问用户："是否采用此草稿？或需要修改？"
4. 用户确认/修改完成后 → 执行保存步骤
```
### 模式 B：用户手动撰写
```
1. 展示下属汇报摘要（来自 leader_report_get_subordinates 结果）
2. 基于摘要，引导用户填写：
- 本模块今日整体进展
- 遇到的问题与风险
- 明日计划
3. 拼合用户输入内容 → 执行保存步骤
```
---
## 保存草稿
```
mcp__huanxi__leader_report_save(
report_date = "YYYY-MM-DD", ← 日期格式
module_id = "<模块ID>", ← 从 modules.json 缓存取
content = "<正文内容>" ← 支持 Markdown
)
```
**返回值**：保存成功后返回草稿 ID，告知用户已保存，询问是否立即提交。
---
## 多模块批量操作
若用户负责多个模块：
```
1. mcp__huanxi__leader_report_get_batch(date, module_ids=[...])
→ 一次获取所有模块的下属汇报情况
2. 逐模块调用 llm_generate_leader_summary 生成草稿
3. 逐模块调用 leader_report_save 保存
4. 统一确认后逐模块提交
```
---
## 内容格式建议（供 AI 生成参考）
```markdown
## 今日进展
- [任务A] 完成 XX 功能开发，进度 80%
- [任务B] 完成接口联调，已提测
## 问题与风险
- 暂无阻塞性问题
## 明日计划
- 继续推进 [任务C]
- 协助 [成员] 解决 XX 问题
```
plugins/huanxi/skills/huanxi-org/SKILL.md
+133
View File
@@ -0,0 +1,133 @@
---
name: huanxi-org
description: "寰汐组织/模块/人员查询。当用户说"我有哪些模块"、"查一下某人账号/ID"、"刷新一下缓存"、"看组织架构"、"谁在哪个模块"、"帮我找一下XXX的用户ID"时触发。提供名字→ID 解析（+resolve）、缓存刷新（+sync）、当前用户（+me）、模块列表（+modules）、组织树（+tree）。"
---
# 寰汐组织与人员查询
**前置条件：先 Read `../huanxi-shared/SKILL.md`（缓存规则 + TTL 策略）**
---
## 核心能力
本技能提供「名字 → ID」解析能力，是所有其他 huanxi-* 技能的依赖。所有操作**缓存优先**。
---
## Shortcuts
| 指令 | 说明 |
|------|------|
| [`+me`](references/resolve-ids.md#me) | 查看当前用户身份（读 me.json，缓存永久） |
| [`+modules`](references/resolve-ids.md#modules) | 列出我参与的所有模块（24h 缓存） |
| [`+resolve`](references/resolve-ids.md) | 把模块名/人员名解析为 ID |
| [`+tree`](#org-tree) | 展示完整组织架构树（实时查询，不缓存） |
| [`+sync`](#sync) | 强制刷新 modules.json + users.json 缓存 |
---
## +me：查看当前用户身份 {#me}
```
Step 1: Read ~/.claude/huanxi-cache/me.json
→ 若存在且有 data 字段：直接展示（永久缓存，无需检查 TTL）
→ 若不存在：执行 Step 2
Step 2: mcp__huanxi__user_get_me()
Step 3: Write ~/.claude/huanxi-cache/me.json:
{ "cached_at": "<ISO8601>", "data": <返回值> }
Step 4: 展示用户信息（name, feishu_user_id, 角色等）
```
---
## +modules：列出参与模块 {#modules}
```
Step 1: Read ~/.claude/huanxi-cache/modules.json → 检查 TTL（24h）
→ 未过期：直接展示
→ 过期或不存在：执行 Step 2
Step 2: mcp__huanxi__module_list()
Step 3: Write ~/.claude/huanxi-cache/modules.json:
{ "cached_at": "<ISO8601>", "data": <返回值> }
Step 4: 展示模块列表（id, name, my_role）
```
---
## +resolve：名字 → ID 解析
详细流程见 [references/resolve-ids.md](references/resolve-ids.md)。
**快速规则：**
- 模块名 → 先查 `modules.json`，未命中则拉 `module_list()`
- 人员名 → 先查 `users.json`，未命中则调 `user_list(name=xxx)`，结果追加写入缓存
- 模糊匹配时若有多个结果，列出候选项让用户选择
---
## +tree：组织架构树 {#org-tree}
```
Step 1: mcp__huanxi__org_get_tree()（不缓存，实时查询）
Step 2: 以树形结构展示组织架构
```
> 组织架构变动相对频繁（人员入离职），不缓存，每次实时查询。
---
## +sync：强制刷新缓存 {#sync}
```
Step 1: mcp__huanxi__module_list()
→ Write ~/.claude/huanxi-cache/modules.json（强制覆盖）
Step 2: mcp__huanxi__user_list()（拉全量用户）
→ Write ~/.claude/huanxi-cache/users.json（强制覆盖）
Step 3: 告知用户：缓存已刷新（模块 N 个，用户 M 人）
```
> **何时需要 +sync**：添加新模块成员后、有新员工入职后、模块结构调整后。
>
> ⚠️ **Token 变更时**：若切换了寰汐账号（修改了 MCP Bearer Token），`me.json` 是永久缓存，+sync 不会更新它。需手动删除 `~/.claude/huanxi-cache/me.json`，再执行 `/huanxi-org +me` 重新获取新身份。
---
## 缓存文件结构参考
**me.json：**
```json
{
"cached_at": "2026-04-13T09:00:00+08:00",
"data": {
"user_id": "123",
"name": "张三",
"feishu_user_id": "ou_xxx"
}
}
```
**modules.json：**
```json
{
"cached_at": "2026-04-13T09:00:00+08:00",
"data": [
{ "id": "mod_001", "name": "前端开发", "my_role": "member" },
{ "id": "mod_002", "name": "后端API", "my_role": "leader" }
]
}
```
**users.json：**
```json
{
"cached_at": "2026-04-13T09:00:00+08:00",
"data": [
{ "user_id": "456", "name": "李四", "feishu_user_id": "ou_yyy" }
]
}
```
plugins/huanxi/skills/huanxi-org/references/resolve-ids.md
+76
View File
@@ -0,0 +1,76 @@
# 名字 → ID 解析
本文件详细说明如何将模块名、人员名解析为系统 ID，所有步骤均**缓存优先**。
---
## 模块名 → 模块 ID {#modules}
```
1. Read ~/.claude/huanxi-cache/modules.json
→ 检查 cached_at，若 age < 24h → 进入匹配逻辑
→ 过期或不存在 → 调用 mcp__huanxi__module_list() 并写入缓存
2. 匹配逻辑：
a. 精确匹配 name == 输入 → 返回 id
b. 精确匹配失败 → 模糊匹配（name.includes(输入) 或 输入.includes(name)）
c. 模糊匹配唯一命中 → 确认并返回 id
d. 多个候选 → 列出候选项，让用户选择
e. 零命中 → 告知用户，建议运行 +sync 刷新缓存
```
**示例：**
- 用户说"前端模块" → 从缓存匹配到 `{ id: "mod_001", name: "前端开发" }` → 返回 `mod_001`
- 用户说"API" → 匹配到 `后端API` → 返回 `mod_002`
- 匹配到多个 → 展示候选列表
---
## 人员名 → 用户 ID {#users}
```
1. Read ~/.claude/huanxi-cache/users.json
→ 检查 cached_at，若 age < 24h → 在 data 数组中查找
2. 查找逻辑：
a. name 精确匹配 → 返回 user_id
b. name 包含输入 → 列出候选
c. 未找到 → 执行 Step 3
3. 缓存未命中时：
a. 调用 mcp__huanxi__user_list(name=<输入>)
b. 将结果追加（合并去重）写入 users.json（不覆盖已有缓存）
c. 重新执行 Step 2 匹配逻辑
4. 仍未找到 → 告知用户姓名不存在，建议确认拼写或运行 +sync
```
**特别注意：**
- `user_id`（系统内部 ID）≠ `feishu_user_id`（飞书 open_id）
- 设置任务执行人用 `user_id`
- 飞书消息通知用 `feishu_user_id`（MCP 内部会自动处理，无需手动区分）
---
## 自动 ID 解析流程（综合示例）
当用户说"创建任务，负责人是李四，模块是前端开发"时：
```
1. 解析模块 → read modules.json → 匹配"前端开发" → mod_001
2. 解析人员 → read users.json → 匹配"李四" → user_id: 456
3. 若任一缓存未命中：先拉 MCP，写缓存，再继续
4. 两个 ID 都拿到后 → 调用 task_create(module_id="mod_001", ...)
5. 创建完成后 → task_set_assignees(task_id, ["456"])
```
---
## 常见错误处理
| 情况 | 处理 |
|------|------|
| 多个同名用户 | 展示完整名单（含部门/角色），让用户指定 |
| 模块名拼写不完整 | 模糊匹配，确认后继续 |
| 缓存文件损坏（JSON 解析失败）| 忽略缓存，直接调 MCP，重建文件 |
| MCP 返回空列表 | 告知用户，建议检查 Token 权限或联系管理员 |
plugins/huanxi/skills/huanxi-report/SKILL.md
+102
View File
@@ -0,0 +1,102 @@
---
name: huanxi-report
description: "寰汐员工日报工作流：查看今日日报状态（+check）、保存草稿（+draft）、提交日报（+submit）、撤回日报（+withdraw）。当用户说"帮我写日报"、"填日报"、"提交日报"、"查看今日汇报情况"时触发。"
---
# 寰汐员工日报
**前置条件：先 Read `../huanxi-shared/SKILL.md`（缓存规则 + TTL 策略）**
---
## 标准工作流（完整流程）
```
Step 0: 确认身份
→ Read ~/.claude/huanxi-cache/me.json（永久缓存）
→ 若 me.json 为空：mcp__huanxi__user_get_me() → 写入缓存
Step 1: 检查是否工作日
→ 查 workdays.json["今日日期"]
→ 未缓存：mcp__huanxi__system_get_workday() → 追加写入 workdays.json
→ 非工作日：告知用户，询问"是否仍要填写？"（不强制中断）
Step 2: 查看今日日报状态
→ mcp__huanxi__report_get_today()
→ submitted → 告知"今日已提交"，询问是否撤回
→ draft/empty → 继续 Step 3
Step 3: 获取待汇报任务并收集内容
→ mcp__huanxi__report_get_tasks_to_report()
→ 展示待汇报任务列表（task_id, name, 模块, 当前进度）
→ 引导用户逐一填写今日进展和完成百分比
→ 详见 references/report-draft.md
Step 4: 保存草稿并展示初稿
→ mcp__huanxi__report_save_draft(items=[...])
→ 展示完整初稿内容供用户预览
Step 5: 询问是否 AI 润色
→ 询问用户："是否需要 AI 润色优化表达？"
→ 用户同意 → mcp__huanxi__llm_polish_report(content=<初稿内容>)
→ 展示润色后版本，与初稿对比
→ 用户选择采用润色版或保留原版
→ 若采用润色版：mcp__huanxi__report_save_draft(items=[...]) 更新草稿
→ 用户拒绝 → 直接进入 Step 6
Step 6: 确认并提交
→ 展示最终内容，等待用户明确确认（"确认"/"提交"/"好的"等）
→ ⚠️ 未收到确认前，禁止调用 report_submit_item
→ 用户确认后：
a. mcp__huanxi__report_get_today() → 获取各条目的 item_id
b. 对每个需提交的草稿条目 → mcp__huanxi__report_submit_item(item_id)
c. 逐条提交，不影响其他条目
→ 详见 references/report-submit.md
```
---
## Shortcuts
| 指令 | 说明 |
|------|------|
| [`+check`](#check) | 查看今日日报状态（已提交/草稿/空） |
| [`+draft`](references/report-draft.md) | 读取待报任务并保存草稿 |
| [`+submit`](references/report-submit.md) | 提交当天日报（必须先确认） |
| `+withdraw` | 撤回已提交日报（询问确认） |
---
## +check：查看今日状态 {#check}
```
1. mcp__huanxi__report_get_today()
2. 展示：
- 提交状态（submitted / draft / 未填）
- 已填任务列表及内容摘要
- 未填/dismissed 任务
3. 若已提交：询问"是否需要撤回修改？"
4. 若草稿：询问"是否继续编辑并提交？"
```
---
## +withdraw：撤回日报
```
1. mcp__huanxi__report_get_today() → 获取各条目状态和 item_id
2. 展示已提交的条目列表，询问用户要撤回哪条（可多选）
3. 等待用户确认（撤回后该条目变为草稿，其他已提交条目不受影响）
4. 对用户选择的每条 → mcp__huanxi__report_withdraw_item(item_id)
5. 告知撤回成功，可重新编辑后用 report_submit_item 重新提交
```
---
## 关键约束
- **禁止自动提交**：Step 6 必须展示内容并等待用户明确确认（"确认"/"提交"/"好的"等），不得自动调用 `report_submit_item`
- **逐条操作，不做全量**：提交/撤回必须使用 `report_submit_item` / `report_withdraw_item`（需传 item_id），禁止批量操作所有条目，除非用户明确要求"全部提交/撤回"
- **dismissed 状态**：用户主动标记"今天不汇报该任务"，dismiss 的条目不计入汇报，不要提示用户补填
- **非工作日**：检测到非工作日时，明确告知但不中断，询问用户意愿
- **已提交则不重复操作**：Step 2 发现已提交时，不继续 Step 3-6，改为询问是否撤回
plugins/huanxi/skills/huanxi-report/references/report-draft.md
+56
View File
@@ -0,0 +1,56 @@
# 保存日报草稿（+draft）
## 前置
已通过 `report_get_tasks_to_report()` 获取待汇报任务列表。
---
## 草稿数据结构
每个 `item` 包含：
| 字段 | 类型 | 说明 |
|------|------|------|
| `task_id` | string | 任务 ID（从待报任务中取） |
| `content` | string | 汇报内容（今日进展） |
| `progress` | int | 任务进度（0-100，整数） |
| `status` | string | 可选，不改变则不传 |
---
## 执行步骤
```
Step 1: 展示待汇报任务列表，引导用户逐一填写内容
格式示例：
┌─────────────────────────────────────────
│ 任务: [前端开发] 完成登录页面 UI 优化
│ 当前进度: 60%
│ 今日进展（请输入）: ___
│ 完成百分比（0-100）: ___
└─────────────────────────────────────────
Step 2: 收集所有填写内容，构建 items 数组
Step 3: [可选] 若用户请求 AI 辅助 → mcp__huanxi__llm_polish_report(content)
将润色建议展示给用户，由用户确认采用哪个版本
Step 4: mcp__huanxi__report_save_draft(items=[
{ task_id: "xxx", content: "...", progress: 80 },
...
])
Step 5: 告知保存结果：
"已保存草稿，共 N 个任务条目。是否现在提交？"
```
---
## 注意事项
- `progress` 是 **整数百分比**（0-100），不是小数
- 用户未填写 `content` 的任务：询问是否 dismiss（今天不汇报）还是暂时跳过
- `report_save_draft` 是 upsert 操作，多次调用不会重复创建
- 草稿保存成功后，下次调用 `report_get_today()` 可看到 draft 状态
plugins/huanxi/skills/huanxi-report/references/report-submit.md
+54
View File
@@ -0,0 +1,54 @@
# 提交日报（+submit）
## 前置条件
- 草稿已通过 `report_save_draft()` 保存
- 用户已查看并确认内容
---
## 执行步骤
```
Step 1: mcp__huanxi__report_get_today() → 获取最新草稿内容
Step 2: 展示完整草稿给用户审阅：
┌─────────────────────────────────────────
│ 📋 今日日报预览（2026-04-13）
│
│ ✅ 完成登录页面 UI 优化（进度 80%）
│ 今日进展：完成了头部导航栏的响应式改造...
│
│ 🔄 接口联调（进度 50%）
│ 今日进展：与后端对接了 3 个接口...
└─────────────────────────────────────────
Step 3: 等待用户明确确认（"确认"/"提交"/"好的"/"ok"等）
⚠️ 未收到确认前，禁止调用 report_submit
Step 4: 对每个需提交的草稿条目（item.status == "draft"）：
mcp__huanxi__report_submit_item(item_id=<item.id>)
逐条提交，不影响其他条目状态
Step 5: 告知提交结果：
"✅ 日报已提交！共 N 个任务条目。"
```
---
## 提交失败处理
| 错误 | 处理方式 |
|------|---------|
| 草稿为空 | 提示用户先填写内容（+draft） |
| 已提交 | 告知已提交，询问是否撤回 |
| 网络错误 | 告知用户，建议稍后重试 |
---
## 重要约束
**禁止自动提交**：无论何种情况，`report_submit_item()` 调用前必须经过用户明确确认。
这是强制规则，不得因为"用户已经填好了"或"工作流要求"而跳过确认步骤。
**逐条提交，不做全量**：需先从 `report_get_today()` 获取各条目的 `item_id`，再逐条调用 `report_submit_item(item_id)`，不得批量提交所有条目（除非用户明确要求"全部提交"）。
plugins/huanxi/skills/huanxi-shared/SKILL.md
+141
View File
@@ -0,0 +1,141 @@
---
name: huanxi-shared
description: "寰汐 MCP 共享基础：本地缓存策略（me/modules/users/workdays）、TTL 规则、缓存读写伪代码、MCP 工具索引。所有 huanxi-* 技能必须先 Read 本文件，再执行各自工作流。"
---
# 寰汐 MCP 共享规则
本技能是所有 `huanxi-*` 技能的**必读前置**，定义缓存策略、工具索引和全局约定。
---
## 必读声明
**所有 huanxi-* 技能开头都必须先 `Read` 本文件（`../huanxi-shared/SKILL.md`），再执行各自工作流。**
---
## 本地缓存机制
缓存文件统一存放在 `~/.claude/huanxi-cache/`。
### 缓存文件清单
| 文件 | 内容 | TTL | 刷新方式 |
|------|------|-----|---------|
| `me.json` | 当前用户身份（user_id, name, feishu_user_id） | 永久 | 手动删除文件 |
| `modules.json` | 我参与的模块列表（id, name, my_role） | 24h | 过期自动重拉 或 `/huanxi-org +sync` |
| `users.json` | 组织用户搜索结果（name/feishu_user_id 索引） | 24h | 过期自动重拉 或 `/huanxi-org +sync` |
| `workdays.json` | 工作日查询结果（date → bool 的 KV 字典） | 永久（按日期 key） | 已有日期不重新查 |
### 缓存读写伪代码
**读缓存（每次使用 MCP 数据前执行此逻辑）：**
```
function read_cache(file, ttl_hours):
1. Read ~/.claude/huanxi-cache/{file}.json
2. 若文件不存在 → cache_miss
3. 读取 cached_at 字段，计算 age = now - cached_at（小时）
4. 若 ttl_hours = Infinity 或 age < ttl_hours → 返回 data 字段（cache_hit）
5. 否则 → cache_miss
function cache_miss_handler(tool_name, params):
1. 调用 MCP 工具：mcp__huanxi__{tool_name}(params)
2. Write ~/.claude/huanxi-cache/{file}.json:
{ "cached_at": "<当前 ISO8601 时间>", "data": <MCP 返回值> }
3. 返回 data
```
**workdays.json 特殊逻辑（按 key 缓存）：**
```
function get_workday(date):
1. Read workdays.json → 得到 { "2026-04-14": true, ... }
2. 若 date 已在 dict 中 → 直接返回
3. 否则 → 调用 mcp__huanxi__system_get_workday(date)
4. 将 {date: result} 追加写入 workdays.json
```
### TTL 快速参考
```
me.json → Infinity（永久，身份不变）
modules.json → 24h
users.json → 24h
workdays.json → Infinity（按 date key，已查过的不再查）
```
---
## MCP 工具索引
寰汐 MCP 工具前缀：`mcp__huanxi__`
### 用户与认证
| 工具 | 用途 | 缓存 |
|------|------|------|
| `user_get_me()` | 获取当前 Token 代表的用户 | → `me.json`（永久）|
### 模块与组织
| 工具 | 用途 | 缓存 |
|------|------|------|
| `module_list(my_role?)` | 列出我参与的模块 | → `modules.json`（24h）|
| `module_get(module_id)` | 获取模块详情（含成员） | 不缓存 |
| `user_list(name?)` | 搜索组织用户 | → `users.json`（24h）|
| `org_get_tree()` | 获取组织架构树 | 不缓存 |
| `people_get_board()` | 人员任务看板 | 不缓存 |
### 任务管理
| 工具 | 用途 | 缓存 |
|------|------|------|
| `task_list_mine()` | 我认领的任务 | 不缓存 |
| `task_list_by_module(module_id)` | 模块下所有任务 | 不缓存 |
| `task_get(task_id)` | 任务详情 | 不缓存 |
| `task_create(...)` | 创建任务 | — |
| `task_update(task_id, ...)` | 更新任务 | — |
| `task_set_assignees(task_id, assignee_ids)` | 设置执行人（幂等） | — |
### 员工日报
| 工具 | 用途 |
|------|------|
| `report_get_today(date?)` | 获取指定日期日报 |
| `report_get_tasks_to_report()` | 获取今日待汇报任务 |
| `report_save_draft(items=[...])` | 批量保存草稿（upsert）|
| `report_submit_item(item_id, date?)` | 提交单条日报条目 |
| `report_withdraw_item(item_id, date?)` | 撤回单条已提交日报条目 |
### 负责人日报
| 工具 | 用途 |
|------|------|
| `leader_report_get_subordinates(date, module_id)` | 查看下属汇报情况 |
| `leader_report_save(report_date, content, module_id?)` | 保存负责人日报草稿 |
| `leader_report_submit(report_date, module_id)` | 提交负责人日报 |
| `leader_report_withdraw(report_date, module_id)` | 撤回负责人日报 |
| `leader_report_get_batch(date, module_ids)` | 批量获取多模块日报 |
### 周报
| 工具 | 用途 |
|------|------|
| `weekly_report_get(year, week)` | 获取指定 ISO 周的周报 |
| `weekly_report_get_batch(year, week, module_ids)` | 批量获取多模块周报 |
| `weekly_report_save(module_id, year, week_number, content?, next_week_plan?)` | 保存周报草稿 |
| `weekly_report_submit(module_id)` | 提交周报 |
| `weekly_report_withdraw(module_id, year?, week_number?)` | 撤回周报 |
### 系统与 LLM
| 工具 | 用途 | 缓存 |
|------|------|------|
| `system_get_workday(date?)` | 查询是否工作日 | → `workdays.json`（永久）|
| `llm_polish_report(content)` | AI 润色日报内容 | — |
| `llm_generate_leader_summary(module_id, date)` | AI 生成负责人日报草稿 | — |
---
## 全局约定
1. **提交前必须确认**：`report_submit`、`leader_report_submit`、`weekly_report_submit` 执行前必须向用户展示内容并等待明确确认，禁止自动提交。
2. **非工作日不强制**：检测到非工作日时，告知用户并询问是否仍要填写，不得直接中断流程。
3. **缓存优先**：执行任何需要 module_id / user_id 的操作前，先读缓存；缓存未命中或过期才调 MCP。
4. **ISO 周数**：周报的 `year` 字段存 ISO year（`date.isocalendar()[0]`），不是日历年。12 月底 / 1 月初注意跨年。
5. **task_set_assignees 幂等**：设置执行人使用此工具（幂等），不要用 task_update 的 assignee 字段追加。
plugins/huanxi/skills/huanxi-task/SKILL.md
+91
View File
@@ -0,0 +1,91 @@
---
name: huanxi-task
description: "寰汐任务管理：创建任务（+create）、更新任务状态/进度（+update）、查看任务看板（+board）、设置执行人（+assign）。当用户说"创建任务"、"新建任务"、"更新任务"、"看任务板"、"任务分配"时触发。"
---
# 寰汐任务管理
**前置条件：先 Read `../huanxi-shared/SKILL.md`（缓存规则 + TTL 策略）**
---
## Shortcuts
| 指令 | 说明 |
|------|------|
| [`+create`](references/task-create.md) | 创建新任务（引导式填写） |
| `+update` | 更新任务状态/进度/截止日 |
| [`+board`](references/task-kanban.md) | 查看我的任务看板 |
| `+assign` | 设置/变更任务执行人 |
| `+get` | 查看单个任务详情 |
---
## +create：创建任务
详见 [references/task-create.md](references/task-create.md)
**快速概览：**
```
1. 确定所属模块（从 modules.json 缓存解析名字 → ID）
2. 收集任务信息（标题、描述、截止日、优先级）
3. mcp__huanxi__task_create(module_id, title, ...)
4. [可选] 设置执行人 → mcp__huanxi__task_set_assignees(task_id, [user_id])
```
---
## +update：更新任务
```
Step 1: 确认任务 ID
→ 若用户已提供 task_id：直接使用
→ 若用户描述了任务名称：
a. mcp__huanxi__task_list_mine() 获取我的任务列表
b. 按标题关键词模糊匹配，列出候选任务供用户选择
c. 仍未找到（可能属于他人或已归档）→ 告知用户提供精确 task_id
Step 2: 展示当前任务状态，引导用户填写要修改的字段
Step 3: mcp__huanxi__task_update(task_id, {
title? : "新标题",
description? : "新描述",
progress? : 80, ← 0-100 整数
status? : "in_progress" | "done" | "todo",
due_date? : "YYYY-MM-DD",
priority? : "low" | "medium" | "high"
})
Step 4: 告知更新结果
```
---
## +assign：设置执行人
```
Step 1: 确认任务 ID
Step 2: 解析执行人名字 → user_id（查 users.json 缓存）
→ 详见 huanxi-org references/resolve-ids.md
Step 3: mcp__huanxi__task_set_assignees(task_id, assignee_ids=[user_id, ...])
（此操作幂等：传完整列表，不是追加）
Step 4: 告知设置结果
```
---
## +get：查看任务详情
```
Step 1: mcp__huanxi__task_get(task_id)
Step 2: 展示完整任务信息（标题/描述/状态/进度/执行人/截止日/评论数）
```
---
## 关键约束
- **任务创建后不自动认领**：`task_create` 不会自动设置执行人，需要单独调用 `task_set_assignees`
- **执行人是完整列表**：`task_set_assignees` 传入的是完整执行人 ID 列表（幂等替换），不是追加
- **progress 是整数**：0-100 的整数，不是小数或百分比字符串
- **模块创建权限**：用户必须是模块成员（任意角色）才能在该模块创建任务，否则返回 403
plugins/huanxi/skills/huanxi-task/references/task-create.md
+69
View File
@@ -0,0 +1,69 @@
# 创建任务（+create）
## 必填信息收集
在调用 `task_create` 前，引导用户提供：
| 字段 | 必填 | 说明 |
|------|------|------|
| `module_id` | ✅ | 所属模块（从缓存解析名字 → ID） |
| `title` | ✅ | 任务标题（简洁明了）|
| `description` | 可选 | 任务详情、背景、验收标准 |
| `due_date` | 可选 | 截止日期（YYYY-MM-DD 格式）|
| `priority` | 可选 | `low` / `medium` / `high` / `urgent`，默认 medium |
| `assignee_ids` | 可选 | 执行人（从缓存解析人名 → user_id）|
---
## 执行步骤
```
Step 1: 解析模块名 → module_id
→ Read ~/.claude/huanxi-cache/modules.json
→ 模糊匹配模块名（详见 huanxi-org resolve-ids.md）
Step 2: [若用户提到执行人] 解析人名 → user_id
→ Read ~/.claude/huanxi-cache/users.json
→ 未命中 → mcp__huanxi__user_list(name=<人名>) → 追加写缓存
Step 3: 创建任务
→ mcp__huanxi__task_create(
module_id = "<模块ID>",
title = "任务标题",
description = "...", ← 可选
due_date = "YYYY-MM-DD", ← 可选
priority = "medium" ← 可选
)
→ 返回：task_id
Step 4: 设置执行人（若 Step 2 有解析到）
→ mcp__huanxi__task_set_assignees(
task_id = "<刚创建的 task_id>",
assignee_ids = ["<user_id>"]
)
Step 5: 告知创建结果
→ 展示：任务标题、所属模块、执行人、截止日、task_id
→ 询问："是否需要进一步调整？"
```
---
## 权限说明
用户必须是所属模块的成员（任意角色）才能创建任务。若返回 403：
- 可能未加入该模块
- 建议联系模块负责人添加成员，或请管理员使用 Admin MCP 操作
---
## 子任务支持
若需创建子任务：
```
mcp__huanxi__task_create(
module_id = "<模块ID>",
title = "子任务标题",
parent_task_id = "<父任务ID>" ← 传此字段即为子任务
)
```
plugins/huanxi/skills/huanxi-task/references/task-kanban.md
+51
View File
@@ -0,0 +1,51 @@
# 任务看板（+board）
## 查看我的任务
```
Step 1: mcp__huanxi__task_list_mine()
→ 返回我认领的所有任务（跨模块）
Step 2: 按状态分组展示：
────────────────────────────────────
📋 待处理（todo）
· [前端开发] 完成登录页面 UI 优化 ← 截止: 04-15
· [后端API] 接口文档更新 ← 无截止日
🔄 进行中（in_progress）
· [前端开发] 接口联调 60% ← 截止: 04-20
✅ 已完成（done）
· [前端开发] 初始化项目结构 100%
────────────────────────────────────
```
## 查看模块看板
```
Step 1: 确认模块（从 modules.json 缓存解析）
Step 2: mcp__huanxi__task_list_by_module(module_id)
→ 返回该模块所有任务（含其他成员的任务）
Step 3: 按状态分组展示，标注每个任务的执行人
```
## 人员任务看板（管理视角）
```
Step 1: mcp__huanxi__people_get_board()
→ 返回团队所有成员的任务分布（数量统计）
Step 2: 展示每人的任务负载情况（适合分配任务前参考）
```
---
## 快速过滤
用户常见需求：
| 场景 | 做法 |
|------|------|
| "我今天要做什么" | task_list_mine() → 过滤 status=in_progress + 截止日临近 |
| "某个模块的任务" | task_list_by_module(module_id) |
| "即将到期的任务" | task_list_mine() → 筛选 due_date ≤ 今日+3天 |
| "团队任务分布" | people_get_board() |
plugins/huanxi/skills/huanxi-weekly/SKILL.md
+131
View File
@@ -0,0 +1,131 @@
---
name: huanxi-weekly
description: "寰汐周报工作流（仅限模块负责人）：查看本周周报状态（+check）、基于本周负责人日报 AI 汇总草稿（+draft）、提交周报（+submit）、撤回（+withdraw）。当用户说"写周报"、"提交周报"、"本周总结"、"周报进度"时触发。"
---
# 寰汐周报（仅限模块负责人）
**前置条件：先 Read `../huanxi-shared/SKILL.md`（缓存规则 + TTL 策略）**
---
## 权限说明
**周报只有模块负责人（`my_role == 'leader'`）才需要提交。**
若用户不是任何模块的负责人：
- 告知："您目前不是任何模块的负责人，无需提交周报。"
- 建议：若有疑问，可联系管理员确认模块角色。
---
## ISO 周数规范（重要）
寰汐周报使用 **ISO 8601 标准**：
- `year` 字段存 **ISO year**（不是日历年）
- 12月底/1月初可能跨年：如 2025-12-29 的 ISO year = 2026（第1周）
- Python 获取：`date.isocalendar()` → `(iso_year, week, weekday)`
**当前日期 → ISO 周号计算示例：**
- 2026-04-13（周一）→ year=2026, week=16
---
## 标准工作流
```
Step 0: 确认负责人身份和模块
→ Read ~/.claude/huanxi-cache/modules.json（24h 缓存）
→ 若过期：mcp__huanxi__module_list() → 更新缓存
→ 筛选 my_role == 'leader' 的模块列表
→ 若列表为空：告知用户无需提交周报，流程终止
→ 若有多个 leader 模块：询问"要提交哪些模块的周报？"
Step 1: 确定当前 ISO 周号
→ 根据今日日期计算 (iso_year, iso_week)
→ 告知：第 iso_week 周（周一 ~ 周日 日期范围）
Step 2: 批量拉取周报草稿
→ mcp__huanxi__weekly_report_get_batch(
year=iso_year,
week=iso_week,
module_ids=[<leader 模块的 ID 列表>]
)
→ 返回：各模块的现有草稿状态
Step 3: 逐日拉取本周负责人日报
→ 计算本周日期范围（周一到今日，YYYY-MM-DD 格式列表）
→ 对每个日期逐一调用：
mcp__huanxi__leader_report_get_batch(
date=<单个日期>,
module_ids=[<leader 模块的 ID 列表>]
)
→ 汇总所有日期的返回数据
→ 展示：本周每日负责人日报记录（含各日进展摘要 + 下属提交情况）
Step 4: 询问是否 AI 汇总
→ 展示本周负责人日报数据后，询问：
"是否需要 AI 根据本周负责人日报自动生成周报草稿？"
→ 用户同意 → AI 基于 leader_report_batch 起草：
· content：本周模块整体进展总结
· next_week_plan：下周模块工作计划
→ 展示草稿，供用户审阅和修改
→ 用户拒绝 → 引导用户手动填写本周总结和下周计划
Step 5: 逐模块保存草稿
→ 详见 references/weekly-draft.md
→ mcp__huanxi__weekly_report_save(module_id, year, week_number, content, next_week_plan)
Step 6: 确认并提交
→ 展示所有模块最终内容，等待用户明确确认（"确认"/"提交"/"好的"等）
→ ⚠️ 未收到确认前，禁止调用 weekly_report_submit
→ mcp__huanxi__weekly_report_submit(module_id)
```
---
## Shortcuts
| 指令 | 说明 |
|------|------|
| `+check` | 查看本周周报状态（草稿/已提交） |
| [`+draft`](references/weekly-draft.md) | 基于本周负责人日报 AI 生成草稿 |
| `+submit` | 提交周报（必须先确认） |
| `+withdraw` | 撤回已提交周报 |
---
## +check：查看本周状态
```
1. 确认 leader 模块列表（同 Step 0）
2. 若无 leader 模块：告知无需提交周报
3. mcp__huanxi__weekly_report_get_batch(year, week, module_ids)
4. 展示各模块周报状态：
- submitted：已提交，展示摘要
- draft：草稿中，展示已填内容
- empty：未填，建议运行 +draft
```
---
## +withdraw：撤回周报
```
1. 确认 leader 模块（从 modules.json 缓存中取）
2. 若有多个 leader 模块，询问要撤回哪个模块的周报
3. 告知撤回影响（状态变为草稿，可重新编辑），等待用户确认
4. mcp__huanxi__weekly_report_withdraw(module_id)
（默认撤回当周；如需撤回历史周：传 year + week_number）
5. 告知成功，可重新编辑后再次提交
```
---
## 关键约束
- **仅负责人可提交**：首先检查 `my_role == 'leader'`，非负责人直接告知无需操作
- **禁止自动提交**：`weekly_report_submit(module_id)` 前必须展示全部内容并等待用户确认
- **year 存 ISO year**：高频出错点，必须使用 `isocalendar()[0]`，不要用 `date.year`
- 每个模块独立提交，有多个模块时逐一处理
- 撤回后可重新编辑，不影响当前状态
plugins/huanxi/skills/huanxi-weekly/references/weekly-draft.md
+97
View File
@@ -0,0 +1,97 @@
# 周报草稿（+draft，仅限模块负责人）
## 数据来源
周报草稿基于**本周负责人日报汇总**（`leader_report_get_batch` 返回值），而非员工个人日报。
| 数据 | 来源 | 说明 |
|------|------|------|
| 本周每日负责人日报 | `leader_report_get_batch(date列表, module_ids)` | 含各日的模块进展 + 下属提交情况摘要 |
| 现有周报草稿 | `weekly_report_get_batch(year, week, module_ids)` | 已填写的草稿（若有） |
---
## 草稿生成步骤
```
Step 1: 解析本周负责人日报数据
→ 按日期排列，提取每日：
· 模块整体进展
· 团队成员提交情况
· 遇到的问题与风险
Step 2: AI 基于负责人日报起草 content（本周总结）：
- 提炼本周模块核心进展（任务推进 + 里程碑）
- 汇总团队整体情况
- 列出本周识别的问题与应对
Step 3: AI 起草 next_week_plan（下周计划）：
- 基于本周未完成项和下周目标
- 结合用户补充的计划
Step 4: 展示草稿给用户审阅修改
Step 5: 用户确认后逐模块保存：
mcp__huanxi__weekly_report_save(
module_id = "<模块ID>",
year = <ISO year>, ← 注意：ISO year，不是日历年
week = <ISO week>,
content = "<本周总结>",
next_week_plan = "<下周计划>"
)
```
---
## 内容格式建议（负责人视角）
**content（本周总结）：**
```markdown
## 本周模块进展
- **[任务A]** 完成 XX 功能开发，进度推进至 80%（负责人：张三）
- **[任务B]** 完成接口联调，已提测（负责人：李四）
## 团队提交情况
本周全员提交日报，无缺报。
## 问题与风险
- [周三] 第三方接口超时问题，已升级厂商处理，预计周一恢复
## 本周总体评估
整体按计划推进，无阻塞性风险。
```
**next_week_plan（下周计划）：**
```markdown
- [任务A] 目标完成剩余 20% 并提测
- [任务B] 协助测试团队完成验收
- 启动 [新需求] 的技术调研
```
---
## 已有草稿处理
若 `weekly_report_get_batch()` 中该模块已有草稿（非 empty）：
- 展示现有草稿内容
- 询问："是在此基础上修改，还是基于本周负责人日报重新生成？"
- 基于用户选择执行对应操作
---
## 多模块处理
```
for module in leader_modules:
1. 提取该模块的 leader_report_batch（本周各日记录）
2. AI 生成草稿（content + next_week_plan）
3. 展示给用户确认/修改
4. weekly_report_save(module_id=module.id, year, week, ...)
5. 告知：模块 "{module.name}" 草稿已保存 ✅
所有模块草稿完成后：统一展示，询问是否提交
```
plugins/memcore/.claude-plugin/plugin.json
+7
View File
@@ -0,0 +1,7 @@
{
"name": "memcore",
"description": "Claude Code 记忆体系核心引擎。提供三层技能：memory-sync（全量同步编排）、memory-update（增量写入）、memory-lint（健康校验）。让项目记忆跨会话、跨机器保持一致。",
"author": {
"name": "蚁熊团队"
}
}
plugins/memcore/skills/memory-lint/SKILL.md
+217
View File
@@ -0,0 +1,217 @@
---
name: memory-lint
description: 检查本地记忆文件的健康状况。AUTO-FIX类问题直接修改本地文件，NEED-HUMAN类问题写入lint_report.md。以本地.claude/memory/为唯一权威，不推送远程。可独立执行，也作为/memory-sync流程的一部分。调用命令: /memory-lint
---
# memory-lint
健康检查 `.claude/memory/`：AUTO-FIX 直修，NEED-HUMAN 写入 `lint_report.md`。**本地权威，不推送远程**。会话目录 = `$PROJECT_DIR`。
目录不存在 → 输出 `⚠ 未找到 .claude/memory/，建议先执行 /memory-sync` 并终止。
---
## Phase 0 — 读取状态
```bash
cat "$PROJECT_DIR/.claude/memory/MEMORY.md"
ls "$PROJECT_DIR/.claude/memory/"*.md
```
提取 `$INDEX_FILES`（索引中的 `[filename.md]`）/ `$DISK_FILES`（磁盘文件）/ `$ANCHOR_COMMIT` / `$LAST_SYNCED`。
---
## Phase 1-2 — 孤儿与幽灵检测
| Phase | 定义 | 级别 | AUTO-FIX |
|-------|------|------|---------|
| 1 孤儿 | 索引有 → 磁盘无 | ERROR | 从 MEMORY.md 删该条目 |
| 2 幽灵 | 磁盘有 → 索引无（排除 MEMORY.md / lint_report.md） | WARN | 补入索引（类型推断见下） |
幽灵类型推断：`user_*` → user / `project_*` 或 `decisions.md` → project / `feedback*` → feedback / `reference*` → reference / `synthesis_*` → synthesis / 其他默认 project。
---
## Phase 3 — 交叉引用完整性
### 3A 存在性检测 + 引用计数构建
扫描所有 `[[filename.md#section]]`，构建：
- **引用表** `源文件#源章节 → 目标文件#目标章节`
- **`$REF_COUNT`**：文件级被引用计数（按源文件去重，不含自引用）→ Phase 7 写入 MEMORY.md「引用」列
- **`$ITEM_REF_COUNT`**：`decisions.md` / `feedback*.md` 中每个 `## 条目`的被引用计数（按源文件去重）→ Phase 8 写入 lint_report.md，供 `/memory-update` 反向触发消费
| 情况 | 级别 | 动作 |
|------|------|-----|
| 目标文件不存在 | ERROR | NEED-HUMAN |
| 章节缺失 + 高相似度匹配（疑似重命名） | WARN | AUTO-FIX 更新引用 |
| 章节缺失 + 无相似项 | WARN | NEED-HUMAN |
### 3B 对称性检测（双链闭环）
复用 3A 引用表，对每条 `A#α → B#β` 检查 B 的 `## β` 是否含任意 `[[A` 引用（不要求精确章节）。
- 级别：WARN
- AUTO-FIX：B 的目标章节末尾追加 `**See Also：** [[A#α]]`
- 边界：`lint_report.md` 不参与；B 整文件无对 A 任何引用 → AUTO-FIX；B 有引用但不在目标章节 → 仅 WARN 不自动修改
---
## Phase 4-6 — NEED-HUMAN 检测族
三类全部为 NEED-HUMAN，写入 lint_report.md 时**必须附带 3 问 yes/no checklist + 决策矩阵**（Phase 8 模板）。
### Phase 4 内容矛盾
| 维度 | 检查 |
|------|------|
| decisions vs feedback | 决策与规范逻辑冲突 |
| decisions vs 架构文件 | 与 pom.xml / package.json / requirements.txt 实际依赖不一致 |
| 多 feedback 文件 | feedback.md 与 feedback_{topic}.md 重复或矛盾 |
| synthesis vs decisions | synthesis 结论与决策抵触 |
```bash
cat "$PROJECT_DIR/pom.xml" || cat "$PROJECT_DIR/package.json" || cat "$PROJECT_DIR/requirements.txt"
```
### Phase 5 过期检测
阈值：WARN ≥30 天 / ERROR ≥90 天（可由 MEMORY.md 头部 `<!-- lint-stale-warn: N -->` 覆盖）。
```bash
git -C "$PROJECT_DIR" log --oneline --since="$last_updated" -- .
```
### Phase 6 可推断内容污染
污染特征：大量文件路径、git 流水账、方法签名/SQL、可从依赖文件直读的版本号列表。
**边界（关键）**：架构层级（"认证模块在 auth/，提供 JWT + OAuth2 双协议"）**保留**；具体类名/方法/路径列表（`AuthFilter.java`）**删除**。
---
## Phase 7 — 执行 AUTO-FIX
按顺序修改本地文件：
1. MEMORY.md 移除孤儿（Phase 1）
2. MEMORY.md 补入幽灵（Phase 2）
3. 更新断链引用（Phase 3A 重命名匹配）
4. 追加反向链接（Phase 3B）
5. **刷新 MEMORY.md 索引「引用」列**（基于 `$REF_COUNT`）：
- 表格统一 5 列：`| 文件 | 描述 | 类型 | 引用 | Commit |`
- 「引用」值 ≥3 加 `*`（如 `5*`）、<3 显示数字（如 `2`、`0`）
- **按引用次数倒序排列**（同次数按类型序：user → project → feedback → reference → synthesis → lint）
- 旧版 `## 核心枢纽节点` 段落自动删除（已合并到主表）
---
## Phase 8 — 生成 lint_report.md
```markdown
---
name: 记忆健康检查报告
description: memory-lint 最新一次执行的检查结果与待处理项
type: lint
last_updated: YYYY-MM-DD
---
# 记忆健康检查报告
> _执行时间: YYYY-MM-DD | Base commit: `HASH` | Last synced: DATE_
## 健康概览
| 检查项 | AUTO-FIX | NEED-HUMAN |
|--------|---------|-----------|
| 1 孤儿 / 2 幽灵 / 3A 引用 / 3B 双链 | N / N / N / N | — / — / N / N |
| 4 矛盾 / 5 过期 / 6 污染 | — | N / N / N |
**AUTO-FIX 已执行 N 项 | NEED-HUMAN 待处理 N 项**
---
## AUTO-FIX 已执行清单
- [x] 移除孤儿：`synthesis_xxx.md`
- [x] 补入幽灵：`feedback_api.md`（feedback）
- [x] 更新断链：`[[feedback.md#API 认证规范]]` → `[[feedback.md#API 鉴权约束]]`
- [x] MEMORY.md「引用」列已刷新（22 文件，倒序）
---
## 条目级高频引用 Top（供 /memory-update 消费）
跨 ≥3 个不同源文件被引用的 decisions/feedback 条目。无候选时保留标题 + "无候选"。
| 条目 | 跨文件次数 | 建议 |
|------|----------|------|
| `architecture_decisions.md#动态API normalizeParams 类型转型` | 4 | 升级为 synthesis_arch_dynamic_api.md |
| `feedback_code_quality.md#JWT 密钥安全` | 3 | 升级为 synthesis_security_jwt.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] 内容矛盾 — 跨文件表述冲突
- **A**：`decisions.md → ## 数据库选型` PostgreSQL（last_updated: 2026-04-22）
- **B**：`project_overview.md → ## 技术栈` MySQL 8.0（last_updated: 2026-02-10）
- **Checklist**：
- Q1：当前代码/配置（pom.xml / docker-compose）实际指向？
- Q2：另一方是「计划未实施」还是「过时记录」？
- Q3：近 30 天 git log 有迁移提交？
- **矩阵**：Q1 答案 = 当前权威；Q2 过时 → 直接更新另一方；Q2 计划 → 末尾标 `**Status:** planned, target HASH`；Q3 有迁移 → 用迁移时间反推
### [WARN] 过期记忆 — last_updated 超阈值
- **文件**：`project_progress.md`（last_updated: 2026-01-15，过期 86 天）
- **Checklist**：
- Q1：覆盖领域近 90 天有里程碑变更？
- Q2：现有内容是否仍可指导决策？
- Q3：是否有继任 synthesis_* 已分担其职责？
- **矩阵**：Q1 是 + Q2 否 → 触发 `/memory-update`；Q2 是（仅日期老）→ 仅刷新 `last_updated`；Q3 是 → 归档/删除，索引指向继任者
### [WARN] 可推断内容污染 — 疑似从代码可 grep 的明细
- **文件**：`project_overview.md` 第 N 行（疑似具体类/路径列表）
- **Checklist**：
- Q1：能否通过 grep / find / git log 直接还原？
- Q2：删除后剩余内容是否仍清晰描述「为什么/约束/边界」？
- Q3：是否承载 git history 抓不到的语义？（如「曾选 A 后改 B 因 X」）
- **矩阵**：Q1+Q2 = 是 + Q3 否 → 安全删除；Q3 是 → 改写为决策格式迁到 decisions.md（保留 Why）；Q2 否 → 保留架构层级描述但删具体路径
```
---
## Phase 9 — 输出摘要
被 `/memory-sync` 调用：
```
🔍 memory-lint：AUTO-FIX N 项，NEED-HUMAN N 项（详见 lint_report.md）
```
独立调用：扩展输出已修复 / 待处理清单 + 报告路径；全通过则 `✅ 记忆体系健康，已更新执行时间`。
每次执行必须更新 lint_report.md（即使全通过也刷新执行时间）。
---
## 执行约束
1. **AUTO-FIX 边界严格** — 只修结构性错误（孤儿、幽灵、断链、双链），不改业务内容
2. **NEED-HUMAN 完整记录** — 每项含 checklist + 决策矩阵
3. **矛盾检测宁缺勿滥** — 措辞不一致 ≠ 矛盾，宁漏报不误报
4. **污染检测边界**（重申）— 架构层级保留 / 具体类名路径删除
5. **被调用静默返回** — `/memory-sync` 内 Phase 9 不输出收尾
plugins/memcore/skills/memory-sync/SKILL.md
+190
View File
@@ -0,0 +1,190 @@
---
name: memory-sync
description: 项目记忆体系完整同步。Git检查→远程补充本地→增量更新记忆文件→lint收敛→CLAUDE.md注入→本地权威推送远程。以本地.claude/memory/为唯一权威基准。调用命令: /memory-sync
---
# memory-sync
记忆体系完整同步周期。**本地 `.claude/memory/` 是唯一权威**，远程为镜像。会话目录 = `$PROJECT_DIR`。
```
Phase 0-4 前置（git + 锚点 + 远程→本地补充 + 多机检测 + diff）
Phase 5 /memory-update（本地写入）
Phase 6 /memory-lint（收敛）
Phase 7-9 CLAUDE.md 维护与记忆引导区块注入
Phase 10 本地 → 远程权威推送
Phase 11 完成报告
```
---
## Phase 0 — Git 检查
```bash
git -C "$PROJECT_DIR" status --short
```
- 有未提交变更 → 展示文件、询问 commit message（默认 `chore: sync before memory update`）→ `git add .claude/memory/ && git commit -m "<msg>"` → 记新 hash
- 干净 → `git rev-parse --short HEAD` → `$HEAD_HASH`
- 非 git 仓库 → 跳过 Phase 0，commit 字段填 `N/A`
---
## Phase 1 — 远程路径
```
$REMOTE_MEMORY = ~/.claude/projects/{PROJECT_KEY}/memory/
PROJECT_KEY = $PROJECT_DIR 中所有 `:` `\` `/` 替换为 `-`
例：C:\Users\skyji\work\api → C--Users-skyji-work-api
```
---
## Phase 2 — 本地目录初始化
```bash
ls "$PROJECT_DIR/.claude/memory/" 2>/dev/null
```
- 不存在 → `mkdir -p` 后跳到 Phase 3（全量从远程拉，跳过差量）
- 存在 → 提取 `MEMORY.md` 头部 `Base commit: \`HASH\`` → `$ANCHOR_COMMIT`（无则空 = 全量）
---
## Phase 3 — 远程 → 本地（只补不覆）
```bash
for f in ~/.claude/projects/{PROJECT_KEY}/memory/*.md; do
fn=$(basename "$f"); local="$PROJECT_DIR/.claude/memory/$fn"
[ ! -f "$local" ] && cp -p "$f" "$local"
done
```
### 多机不同步检测
两边都存在的文件，对比 mtime：
```bash
for f in ~/.claude/projects/{PROJECT_KEY}/memory/*.md; do
local="$PROJECT_DIR/.claude/memory/$(basename "$f")"
[ ! -f "$local" ] && continue
rm=$(stat -c %Y "$f" 2>/dev/null || stat -f %m "$f")
lm=$(stat -c %Y "$local" 2>/dev/null || stat -f %m "$local")
diff_days=$(( (rm - lm) / 86400 ))
[ $diff_days -ge 7 ] && echo "⚠ $(basename "$f") 远程比本地新 $diff_days 天"
done
```
≥1 个警告 → 提示 `检测到 N 个文件远程比本地新 ≥7 天，可能多机不同步。继续？(y/n)`。
- `n` → 终止整个 sync 流程
- `y` → 继续（Phase 10 仍按本地权威覆盖远程）
---
## Phase 4 — diff 范围
```bash
[ -n "$ANCHOR_COMMIT" ] && git diff --name-only $ANCHOR_COMMIT..HEAD # → $CHANGED_FILES
```
空锚点 → `$CHANGED_FILES = 全量`。
---
## Phase 5 — 执行 /memory-update
按 git diff 增量更新记忆文件 + MEMORY.md 索引。**完成立即继续 Phase 6，不暂停不收尾**。
---
## Phase 6 — 执行 /memory-lint
全量健康检查：AUTO-FIX 直修，NEED-HUMAN 写 `lint_report.md`。**完成立即继续 Phase 7，不暂停不收尾**。
---
## Phase 7 — CLAUDE.md 新建（若不存在）
执行 `/init` → 文件顶部加 `<!-- Last updated: YYYY-MM-DD | Commit: HASH -->` → 跳到 Phase 9。**简体中文，仅命令/代码保留原文**。
---
## Phase 8 — CLAUDE.md 增量更新（若已存在）
1. 提取顶部 `<!-- Last updated: ... | Commit: HASH -->` 的 HASH → `$CLAUDE_MD_COMMIT`
2. `git diff $CLAUDE_MD_COMMIT..HEAD -- .`
3. 按 diff 内容针对性修改章节（技术栈/模块/命令变化等），不重写全文
4. 更新顶部元数据日期与 commit
**简体中文，仅命令/代码保留原文**。
---
## Phase 9 — 记忆引导区块注入
读 `MEMORY.md` 索引，按以下骨架生成区块（动态填充清单）；CLAUDE.md 已含 `## 记忆体系（会话启动必读）` → 整块替换，否则追加末尾。
```markdown
## 记忆体系（会话启动必读）
> 每次新会话或长会话压缩后，必须先读 `MEMORY.md` 索引再按需加载文件。代码与记忆冲突 → 以代码为准并更新记忆。
### 读取流程
1. `cat .claude/memory/MEMORY.md` 获取清单
2. **必读**（type=`project`/`feedback`）：decisions.md / feedback.md / project_progress.md（按 MEMORY.md 实际动态生成）
3. **按需**（type=`user`/`reference`/`synthesis`/`lint`）：架构讨论时读 project_overview.md / 个性化时读 user_profile.md / 外部集成读 reference.md / 特定主题读 feedback_{topic}.md / 技术决策读 synthesis_*.md
### 记忆目录骨架
.claude/memory/
├── MEMORY.md / decisions.md / feedback*.md / project_*.md / reference.md
├── user_profile.md
├── synthesis_*.md（按需）
└── lint_report.md（按需）
```
**动态调整**：从 MEMORY.md 表格筛 `project`/`feedback` → 必读；`user`/`reference`/`synthesis`/`lint` → 按需。区块清单必须与索引严格一致。
---
## Phase 10 — 本地 → 远程推送（权威覆盖）
```bash
mkdir -p ~/.claude/projects/{PROJECT_KEY}/memory/
cp -pf "$PROJECT_DIR/.claude/memory/"*.md ~/.claude/projects/{PROJECT_KEY}/memory/
```
统一推送 update + lint 的全部本地结果。
---
## Phase 11 — 完成报告
```
✓ memory-sync 完成
📋 CLAUDE.md [已更新 / 已新建 / 无变更]
📖 记忆引导区块 [已注入 / 已刷新 / 无变更]
🧠 memory-update：N 个文件已更新（commit HASH）
🔍 memory-lint：AUTO-FIX N 项 / NEED-HUMAN N 项（详见 lint_report.md）
🌟 核心枢纽节点（被引用 ≥3 次的 Top3，源：MEMORY.md「引用」列）：
- architecture_decisions.md (5*)
- dev_workflow.md (4*)
📊 高频引用条目候选 synthesis 升级（源：lint_report.md「条目级高频引用 Top」；本段是聚合）：
- architecture_decisions.md#动态API normalizeParams 类型转型 (跨 4 文件)
📤 已同步 N 个文件到远程
🔗 Base commit: HASH
```
---
## 执行约束
1. **Phase 0 最先** — 有未提交代码不允许跳过
2. **方向严格区分** — Phase 3 只补充 / Phase 10 才覆盖
3. **顺序固定** — Phase 5（update）→ Phase 6（lint）；lint 在 update 写入完毕后检查
4. **统一推送** — update + lint 修改全部本地完成后由 Phase 10 一次推
5. **记忆引导区块强制存在** — 每次 sync 后 CLAUDE.md 必须含最新区块，文件清单与 MEMORY.md 严格一致
plugins/memcore/skills/memory-update/SKILL.md
+141
View File
@@ -0,0 +1,141 @@
---
name: memory-update
description: 根据git diff增量范围，更新本地记忆文件和MEMORY.md索引。以本地.claude/memory/为唯一权威，不推送远程。可独立执行，也作为/memory-sync流程的一部分。调用命令: /memory-update
---
# memory-update
按 git diff 增量更新本地 `.claude/memory/`。**本地权威，仅操作本地文件**。会话目录 = `$PROJECT_DIR`；目录不存在则 `mkdir -p`。
---
## Phase 1 — 读取增量锚点
```bash
# MEMORY.md 头部 _Last synced: DATE | Base commit: `HASH`_ → $ANCHOR_COMMIT（无则空=全量）
git -C "$PROJECT_DIR" rev-parse --short HEAD # → $HEAD_HASH（非 git 仓库填 N/A）
```
---
## Phase 2 — 计算变更范围
```bash
[ -n "$ANCHOR_COMMIT" ] && git diff --name-only $ANCHOR_COMMIT..HEAD # → $CHANGED_FILES
```
空锚点 → 全量审查。
---
## Phase 3 — 更新记忆文件
### 维度路由（$CHANGED_FILES → 目标文件）
| 变更内容 | 写入到 |
|---------|-------|
| 业务代码（`*.java/py/ts/vue`） | `project_overview.md` `decisions.md` |
| 依赖文件（pom.xml / requirements.txt / package.json） | `project_overview.md` |
| 进度信号（功能完成、Issue 关闭） | `project_progress.md` |
| 协作反馈（用户纠正、规范变更） | `feedback.md` 或 `feedback_{topic}.md` |
| 外部 URL | `reference.md` |
| 用户偏好/风格 | `user_profile.md` |
### 文件职责边界
| 文件 | 类型 | 写 | 不写 |
|------|------|---|------|
| `user_profile.md` | user | 角色、背景、偏好 | 任务进度 |
| `project_overview.md` | project | 技术栈、架构、目录、约定 | 可推断细节 |
| `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
---
```
### 条目格式（decisions / feedback 通用骨架）
```markdown
## 标题
**结论**（feedback 改为规范描述）：xxx
**Why：** 背景、约束、历史教训
**How to apply：** 何时适用、边界
**See Also：** [[file.md#标题]]
```
`synthesis_*.md` 是完整文件而非条目，含 4 段：`## 背景` / `## 分析过程`（提炼，非逐字记录）/ `## 结论`（含 Why + How to apply）/ `## See Also`。
### 交叉引用（双向）
新增 decisions / feedback 条目时：
1. 扫描其他记忆文件标题
2. 主题相关 → 新条目末尾追加 `[[file.md#标题]]`
3. **反向也补**：被引用的旧条目末尾补充对新条目的引用
### synthesis 双触发模式
**A. 会话内主动**：会话出现技术选型对比 / Bug 根因 / 架构演进 / 性能安全分析时，主动提议归档为 `synthesis_{type}_{topic}.md`。
**B. 反向引用触发**：
1. 读 `lint_report.md`「条目级高频引用 Top」段（≥3 跨文件 = 候选）
2. 检查候选是否已有对应 `synthesis_*`（前缀匹配 + 标题语义）
3. 未升级候选 → 提议：
```
📊 高频引用候选升级 synthesis：
[条目]（被 N 文件引用）→ 建议归档为 synthesis_xxx.md
是否归档？(y/n/skip-all)
```
4. `y` → 创建文件 + 在原条目末尾加 `**Synthesized:** [[xxx.md]]`
5. `n` → 原条目末尾加 `<!-- synthesis-decline: YYYY-MM-DD -->`，30 天免打扰
6. `skip-all` → 本次不再提议
### 写入要点
- 仅更新有变化维度，不重写无关文件
- 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` Phase 7 刷新）
- 「引用」列语义：≥3 加 `*`（如 `5*`）、<3 显示数字
- 表格排序由 lint 重排，本 Phase 不强制
被 `/memory-sync` 调用 → 不输出收尾；独立调用 → 输出完整摘要。
---
## 执行约束
1. **最小化更新** — 不写无变化维度
2. **不记录可推断内容** — 实现细节、文件路径、git 历史不入库
3. **feedback 拆分** — 同主题 >5 条规则 → 拆出 `feedback_{topic}.md`
4. **See Also 双向同步** — 新增时扫关联并双向补
5. **synthesis 双触发** — 会话主动 + lint Top 反向；`**Synthesized:**` 标记不可覆盖；`<!-- synthesis-decline -->` 标记 30 天免打扰
6. **被调用静默返回** — `/memory-sync` 内执行不输出收尾