From 0c46ed0306f97312cc805b3d19366d2fb141b629 Mon Sep 17 00:00:00 2001 From: SkyJourney Date: Fri, 1 May 2026 12:04:12 +0800 Subject: [PATCH] chore: sync before memory update --- .claude-plugin/marketplace.json | 15 +- CLAUDE.md | 87 +++++++ .../example-skill/.claude-plugin/plugin.json | 8 - plugins/example-skill/skills/example/SKILL.md | 7 - plugins/huanxi/.claude-plugin/plugin.json | 24 ++ plugins/huanxi/skills/huanxi-leader/SKILL.md | 99 ++++++++ .../references/leader-summary.md | 74 ++++++ plugins/huanxi/skills/huanxi-org/SKILL.md | 133 +++++++++++ .../huanxi-org/references/resolve-ids.md | 76 ++++++ plugins/huanxi/skills/huanxi-report/SKILL.md | 102 ++++++++ .../huanxi-report/references/report-draft.md | 56 +++++ .../huanxi-report/references/report-submit.md | 54 +++++ plugins/huanxi/skills/huanxi-shared/SKILL.md | 141 ++++++++++++ plugins/huanxi/skills/huanxi-task/SKILL.md | 91 ++++++++ .../huanxi-task/references/task-create.md | 69 ++++++ .../huanxi-task/references/task-kanban.md | 51 ++++ plugins/huanxi/skills/huanxi-weekly/SKILL.md | 131 +++++++++++ .../huanxi-weekly/references/weekly-draft.md | 97 ++++++++ plugins/memcore/.claude-plugin/plugin.json | 7 + plugins/memcore/skills/memory-lint/SKILL.md | 217 ++++++++++++++++++ plugins/memcore/skills/memory-sync/SKILL.md | 190 +++++++++++++++ plugins/memcore/skills/memory-update/SKILL.md | 141 ++++++++++++ 22 files changed, 1850 insertions(+), 20 deletions(-) create mode 100644 CLAUDE.md delete mode 100644 plugins/example-skill/.claude-plugin/plugin.json delete mode 100644 plugins/example-skill/skills/example/SKILL.md create mode 100644 plugins/huanxi/.claude-plugin/plugin.json create mode 100644 plugins/huanxi/skills/huanxi-leader/SKILL.md create mode 100644 plugins/huanxi/skills/huanxi-leader/references/leader-summary.md create mode 100644 plugins/huanxi/skills/huanxi-org/SKILL.md create mode 100644 plugins/huanxi/skills/huanxi-org/references/resolve-ids.md create mode 100644 plugins/huanxi/skills/huanxi-report/SKILL.md create mode 100644 plugins/huanxi/skills/huanxi-report/references/report-draft.md create mode 100644 plugins/huanxi/skills/huanxi-report/references/report-submit.md create mode 100644 plugins/huanxi/skills/huanxi-shared/SKILL.md create mode 100644 plugins/huanxi/skills/huanxi-task/SKILL.md create mode 100644 plugins/huanxi/skills/huanxi-task/references/task-create.md create mode 100644 plugins/huanxi/skills/huanxi-task/references/task-kanban.md create mode 100644 plugins/huanxi/skills/huanxi-weekly/SKILL.md create mode 100644 plugins/huanxi/skills/huanxi-weekly/references/weekly-draft.md create mode 100644 plugins/memcore/.claude-plugin/plugin.json create mode 100644 plugins/memcore/skills/memory-lint/SKILL.md create mode 100644 plugins/memcore/skills/memory-sync/SKILL.md create mode 100644 plugins/memcore/skills/memory-update/SKILL.md diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 29aacc2..65efa9d 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -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（健康校验）" } ] } diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..d26793f --- /dev/null +++ b/CLAUDE.md @@ -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/ +└── / # 每个插件独占一个子目录 + ├── .claude-plugin/ + │ └── plugin.json # 插件元数据（name, description, version, author） + └── skills/ + └── / + └── SKILL.md # 技能实现（frontmatter + Markdown 指令） +``` + +## 核心文件格式 + +### marketplace.json（市场索引） + +```json +{ + "name": "yixiong-claude-hub", + "owner": { "name": "蚁熊团队" }, + "description": "...", + "plugins": [ + { "name": "", "source": "./plugins/", "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//` +2. 创建 `plugins//.claude-plugin/plugin.json` +3. 在 `plugins//skills//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 ← 健康校验，可独立执行 +``` + diff --git a/plugins/example-skill/.claude-plugin/plugin.json b/plugins/example-skill/.claude-plugin/plugin.json deleted file mode 100644 index 70e9f06..0000000 --- a/plugins/example-skill/.claude-plugin/plugin.json +++ /dev/null @@ -1,8 +0,0 @@ -{ - "name": "example-skill", - "description": "示例插件", - "version": "1.0.0", - "author": { - "name": "蚁熊团队" - } -} diff --git a/plugins/example-skill/skills/example/SKILL.md b/plugins/example-skill/skills/example/SKILL.md deleted file mode 100644 index 905c972..0000000 --- a/plugins/example-skill/skills/example/SKILL.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -description: 示例技能，用于验证 marketplace 安装流程是否正常 ---- - -这是一个示例技能。当你成功安装并调用它时，说明你的公司内部 marketplace 已经配置成功。 - -请回复：marketplace 安装验证通过！ diff --git a/plugins/huanxi/.claude-plugin/plugin.json b/plugins/huanxi/.claude-plugin/plugin.json new file mode 100644 index 0000000..c5ded68 --- /dev/null +++ b/plugins/huanxi/.claude-plugin/plugin.json @@ -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}" + } + } + } +} diff --git a/plugins/huanxi/skills/huanxi-leader/SKILL.md b/plugins/huanxi/skills/huanxi-leader/SKILL.md new file mode 100644 index 0000000..fc0cfa7 --- /dev/null +++ b/plugins/huanxi/skills/huanxi-leader/SKILL.md @@ -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` 填写员工日报 diff --git a/plugins/huanxi/skills/huanxi-leader/references/leader-summary.md b/plugins/huanxi/skills/huanxi-leader/references/leader-summary.md new file mode 100644 index 0000000..aa88f40 --- /dev/null +++ b/plugins/huanxi/skills/huanxi-leader/references/leader-summary.md @@ -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 问题 +``` diff --git a/plugins/huanxi/skills/huanxi-org/SKILL.md b/plugins/huanxi/skills/huanxi-org/SKILL.md new file mode 100644 index 0000000..36134ee --- /dev/null +++ b/plugins/huanxi/skills/huanxi-org/SKILL.md @@ -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": "", "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": "", "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" } + ] +} +``` diff --git a/plugins/huanxi/skills/huanxi-org/references/resolve-ids.md b/plugins/huanxi/skills/huanxi-org/references/resolve-ids.md new file mode 100644 index 0000000..3488e7c --- /dev/null +++ b/plugins/huanxi/skills/huanxi-org/references/resolve-ids.md @@ -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 权限或联系管理员 | diff --git a/plugins/huanxi/skills/huanxi-report/SKILL.md b/plugins/huanxi/skills/huanxi-report/SKILL.md new file mode 100644 index 0000000..d593c46 --- /dev/null +++ b/plugins/huanxi/skills/huanxi-report/SKILL.md @@ -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，改为询问是否撤回 diff --git a/plugins/huanxi/skills/huanxi-report/references/report-draft.md b/plugins/huanxi/skills/huanxi-report/references/report-draft.md new file mode 100644 index 0000000..63f51fb --- /dev/null +++ b/plugins/huanxi/skills/huanxi-report/references/report-draft.md @@ -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 状态 diff --git a/plugins/huanxi/skills/huanxi-report/references/report-submit.md b/plugins/huanxi/skills/huanxi-report/references/report-submit.md new file mode 100644 index 0000000..85f5fab --- /dev/null +++ b/plugins/huanxi/skills/huanxi-report/references/report-submit.md @@ -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=) + 逐条提交，不影响其他条目状态 + +Step 5: 告知提交结果： + "✅ 日报已提交！共 N 个任务条目。" +``` + +--- + +## 提交失败处理 + +| 错误 | 处理方式 | +|------|---------| +| 草稿为空 | 提示用户先填写内容（+draft） | +| 已提交 | 告知已提交，询问是否撤回 | +| 网络错误 | 告知用户，建议稍后重试 | + +--- + +## 重要约束 + +**禁止自动提交**：无论何种情况，`report_submit_item()` 调用前必须经过用户明确确认。 +这是强制规则，不得因为"用户已经填好了"或"工作流要求"而跳过确认步骤。 + +**逐条提交，不做全量**：需先从 `report_get_today()` 获取各条目的 `item_id`，再逐条调用 `report_submit_item(item_id)`，不得批量提交所有条目（除非用户明确要求"全部提交"）。 diff --git a/plugins/huanxi/skills/huanxi-shared/SKILL.md b/plugins/huanxi/skills/huanxi-shared/SKILL.md new file mode 100644 index 0000000..db184b3 --- /dev/null +++ b/plugins/huanxi/skills/huanxi-shared/SKILL.md @@ -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": } + 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 字段追加。 diff --git a/plugins/huanxi/skills/huanxi-task/SKILL.md b/plugins/huanxi/skills/huanxi-task/SKILL.md new file mode 100644 index 0000000..aa3109f --- /dev/null +++ b/plugins/huanxi/skills/huanxi-task/SKILL.md @@ -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 diff --git a/plugins/huanxi/skills/huanxi-task/references/task-create.md b/plugins/huanxi/skills/huanxi-task/references/task-create.md new file mode 100644 index 0000000..c48ddc2 --- /dev/null +++ b/plugins/huanxi/skills/huanxi-task/references/task-create.md @@ -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 = [""] + ) + +Step 5: 告知创建结果 + → 展示：任务标题、所属模块、执行人、截止日、task_id + → 询问："是否需要进一步调整？" +``` + +--- + +## 权限说明 + +用户必须是所属模块的成员（任意角色）才能创建任务。若返回 403： +- 可能未加入该模块 +- 建议联系模块负责人添加成员，或请管理员使用 Admin MCP 操作 + +--- + +## 子任务支持 + +若需创建子任务： +``` +mcp__huanxi__task_create( + module_id = "<模块ID>", + title = "子任务标题", + parent_task_id = "<父任务ID>" ← 传此字段即为子任务 +) +``` diff --git a/plugins/huanxi/skills/huanxi-task/references/task-kanban.md b/plugins/huanxi/skills/huanxi-task/references/task-kanban.md new file mode 100644 index 0000000..5a21688 --- /dev/null +++ b/plugins/huanxi/skills/huanxi-task/references/task-kanban.md @@ -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() | diff --git a/plugins/huanxi/skills/huanxi-weekly/SKILL.md b/plugins/huanxi/skills/huanxi-weekly/SKILL.md new file mode 100644 index 0000000..df1ce51 --- /dev/null +++ b/plugins/huanxi/skills/huanxi-weekly/SKILL.md @@ -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=[] + ) + → 返回：各模块的现有草稿状态 + +Step 3: 逐日拉取本周负责人日报 + → 计算本周日期范围（周一到今日，YYYY-MM-DD 格式列表） + → 对每个日期逐一调用： + mcp__huanxi__leader_report_get_batch( + date=<单个日期>, + module_ids=[] + ) + → 汇总所有日期的返回数据 + → 展示：本周每日负责人日报记录（含各日进展摘要 + 下属提交情况） + +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` +- 每个模块独立提交，有多个模块时逐一处理 +- 撤回后可重新编辑，不影响当前状态 diff --git a/plugins/huanxi/skills/huanxi-weekly/references/weekly-draft.md b/plugins/huanxi/skills/huanxi-weekly/references/weekly-draft.md new file mode 100644 index 0000000..da59a3e --- /dev/null +++ b/plugins/huanxi/skills/huanxi-weekly/references/weekly-draft.md @@ -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，不是日历年 + 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}" 草稿已保存 ✅ + +所有模块草稿完成后：统一展示，询问是否提交 +``` diff --git a/plugins/memcore/.claude-plugin/plugin.json b/plugins/memcore/.claude-plugin/plugin.json new file mode 100644 index 0000000..65e3191 --- /dev/null +++ b/plugins/memcore/.claude-plugin/plugin.json @@ -0,0 +1,7 @@ +{ + "name": "memcore", + "description": "Claude Code 记忆体系核心引擎。提供三层技能：memory-sync（全量同步编排）、memory-update（增量写入）、memory-lint（健康校验）。让项目记忆跨会话、跨机器保持一致。", + "author": { + "name": "蚁熊团队" + } +} diff --git a/plugins/memcore/skills/memory-lint/SKILL.md b/plugins/memcore/skills/memory-lint/SKILL.md new file mode 100644 index 0000000..5801d7e --- /dev/null +++ b/plugins/memcore/skills/memory-lint/SKILL.md @@ -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 头部 `` 覆盖）。 + +```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 不输出收尾 diff --git a/plugins/memcore/skills/memory-sync/SKILL.md b/plugins/memcore/skills/memory-sync/SKILL.md new file mode 100644 index 0000000..10725aa --- /dev/null +++ b/plugins/memcore/skills/memory-sync/SKILL.md @@ -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 ""` → 记新 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` → 文件顶部加 `` → 跳到 Phase 9。**简体中文，仅命令/代码保留原文**。 + +--- + +## Phase 8 — CLAUDE.md 增量更新（若已存在） + +1. 提取顶部 `` 的 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 严格一致 diff --git a/plugins/memcore/skills/memory-update/SKILL.md b/plugins/memcore/skills/memory-update/SKILL.md new file mode 100644 index 0000000..af9e292 --- /dev/null +++ b/plugins/memcore/skills/memory-update/SKILL.md @@ -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` → 原条目末尾加 ``，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:**` 标记不可覆盖；`` 标记 30 天免打扰 +6. **被调用静默返回** — `/memory-sync` 内执行不输出收尾