feat(huanxi+memcore): 全量修正 huanxi 技能描述漂移 + memcore 七项优化

- huanxi: 更新 MCP URL 至 huanxi.office.yixiong-tech.com - huanxi: 修正所有技能与后端 docstring 漂移 · report items 字段表（补 module_id 必填、progress→progress_update、去除虚构 status） · weekly_report_save week→week_number · task end_date（非 due_date）、critical（非 urgent）、not_started（非 todo） · 用户/模块 ID 字段名统一为 id（非 user_id） · 所有 references 顶部声明"参数细节以 MCP docstring 为准" - memcore: 新增 memcore-shared 共享层（路径锁定 + 全局常量 + PROJECT_DIR 跨平台解析） - memcore: lint_report 增量保活（NEED-HUMAN 稳定 ID + resolved 跳过） - memcore: synonyms.md 自动登记入索引 - memcore: SYNTHESIS_THRESHOLD / LINT_STALE_*_DAYS / MULTI_HOST_WARN_DAYS 常量化 - memcore: update Phase 1 增加 Base commit 兜底，防锚点丢失雪崩 - memcore: Phase 3C 引用快扫脚本改用 grep -F + -- 兼容中文/空格 title Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
2026-06-12 19:13:21 +08:00
parent 4bf58796cf
commit 38beecb2d0
17 changed files with 362 additions and 112 deletions
@@ -15,7 +15,7 @@
  "mcpServers": {
    "huanxi": {
      "type": "http",
-      "url": "https://huanxi.yixiong-tech.com:18085/mcp/",
+      "url": "https://huanxi.office.yixiong-tech.com/mcp/",
      "headers": {
        "Authorization": "Bearer ${user_config.token}"
      }
@@ -1,5 +1,7 @@
 # 负责人日报草稿（+draft）

+> ⚠️ 参数细节以 MCP `leader_report_save` / `llm_generate_leader_summary` 的 docstring 为准，本文档仅做工作流引导。
+
 ## 两种草稿模式

 ### 模式 A：AI 自动生成
@@ -29,13 +31,22 @@
 ```
 mcp__huanxi__leader_report_save(
  report_date = "YYYY-MM-DD",  ← 日期格式
-  module_id   = "<模块ID>",    ← 从 modules.json 缓存取
-  content     = "<正文内容>"   ← 支持 Markdown
+  scope_type  = "module",      ← 默认 "module"；组织维度填 "org"
+  module_id   = "<模块ID>",    ← scope_type="module" 时必填，从 modules.json 缓存取
+  # org_id   = "<组织ID>",     ← scope_type="org" 时必填，与 module_id 互斥
+  content     = "<正文内容>",  ← 支持 Markdown，三段式（今日进展/问题与风险/明日重点）
+  # progress_corrections = [   ← 可选：手动修正模块进度
+  #   { "module_id": "<id>", "new_progress": 75 }
+  # ]
 )
 ```

 **返回值**：保存成功后返回草稿 ID，告知用户已保存，询问是否立即提交。

+**注意**：
+- 同一用户同一日期同一 scope 只有一条记录（重复调用是更新）
+- 默认走 module 维度；只有组织负责人需要 org 维度时才传 `scope_type="org"` + `org_id`
+
 ---

 ## 多模块批量操作
@@ -104,13 +104,15 @@ Step 3: 告知用户：缓存已刷新（模块 N 个，用户 M 人）
 {
  "cached_at": "2026-04-13T09:00:00+08:00",
  "data": {
-    "user_id": "123",
+    "id": "123",
    "name": "张三",
    "feishu_user_id": "ou_xxx"
  }
 }
 ```

+> ⚠️ 用户身份的系统内部 ID 字段名是 `id`（与后端 `user_get_me` / `user_list` 返回结构一致），不是 `user_id`。
+
 **modules.json：**
 ```json
 {
@@ -127,7 +129,7 @@ Step 3: 告知用户：缓存已刷新（模块 N 个，用户 M 人）
 {
  "cached_at": "2026-04-13T09:00:00+08:00",
  "data": [
-    { "user_id": "456", "name": "李四", "feishu_user_id": "ou_yyy" }
+    { "id": "456", "name": "李四", "feishu_user_id": "ou_yyy" }
  ]
 }
 ```
@@ -1,7 +1,11 @@
 # 名字 → ID 解析

+> ⚠️ 参数细节以 MCP `module_list` / `user_list` / `user_get_me` 的 docstring 为准，本文档仅做工作流引导。
+
 本文件详细说明如何将模块名、人员名解析为系统 ID，所有步骤均**缓存优先**。

+**字段名约定**：用户/模块的系统内部 ID 字段名统一为 `id`（与后端返回结构一致），不要写成 `user_id`/`module_id` 作为 JSON 字段名。`module_id`/`user_id` 仅在传入 MCP 工具参数时使用。
+
 ---

 ## 模块名 → 模块 ID {#modules}
@@ -33,7 +37,7 @@
   → 检查 cached_at，若 age < 24h → 在 data 数组中查找

 2. 查找逻辑：
-   a. name 精确匹配 → 返回 user_id
+   a. name 精确匹配 → 返回 user.id
   b. name 包含输入 → 列出候选
   c. 未找到 → 执行 Step 3

@@ -46,8 +50,8 @@
 ```

 **特别注意：**
- `user_id`（系统内部 ID）≠ `feishu_user_id`（飞书 open_id）
- 设置任务执行人用 `user_id`
+- 用户的系统内部 ID 字段名是 `id`（后端 `user_list` 返回结构），`≠ feishu_user_id`（飞书 open_id）
+- 设置任务执行人时，MCP 工具的参数名叫 `assignee_ids`，传入的值就是 user.id 列表
 - 飞书消息通知用 `feishu_user_id`（MCP 内部会自动处理，无需手动区分）

 ---
@@ -58,7 +62,7 @@

 ```
 1. 解析模块 → read modules.json → 匹配"前端开发" → mod_001
-2. 解析人员 → read users.json → 匹配"李四" → user_id: 456
+2. 解析人员 → read users.json → 匹配"李四" → id: 456
 3. 若任一缓存未命中：先拉 MCP，写缓存，再继续
 4. 两个 ID 都拿到后 → 调用 task_create(module_id="mod_001", ...)
 5. 创建完成后 → task_set_assignees(task_id, ["456"])
@@ -28,12 +28,14 @@ Step 2: 查看今日日报状态

 Step 3: 获取待汇报任务并收集内容
  → mcp__huanxi__report_get_tasks_to_report()
-  → 展示待汇报任务列表（task_id, name, 模块, 当前进度）
+  → 返回的每个任务条目含：id（task_id）、title、module_id、module_name、progress 等
+  → 展示待汇报任务列表（任务名、模块、当前进度）
  → 引导用户逐一填写今日进展和完成百分比
  → 详见 references/report-draft.md

 Step 4: 保存草稿并展示初稿
  → mcp__huanxi__report_save_draft(items=[...])
+  → ⚠️ items 字段以 MCP docstring 为准；每条必须带 module_id（取自 Step 3 任务条目）
  → 展示完整初稿内容供用户预览

 Step 5: 询问是否 AI 润色
@@ -1,21 +1,23 @@
 # 保存日报草稿（+draft）

+> ⚠️ 参数细节以 MCP `report_save_draft` 的 docstring 为准，本文档仅做工作流引导。
+
 ## 前置

-已通过 `report_get_tasks_to_report()` 获取待汇报任务列表。
+已通过 `report_get_tasks_to_report()` 获取待汇报任务列表。返回的每个任务条目至少含 `id`（task_id）、`title`、`module_name`，**以及 module_id 字段**（保存草稿必需）。

 ---

-## 草稿数据结构
+## items 字段（与后端签名一致）

-每个 `item` 包含：
+| 字段 | 必填 | 类型 | 说明 |
+|------|------|------|------|
+| `module_id` | ✅ **必填** | string (UUID) | 任务所属模块 ID，从 `report_get_tasks_to_report()` 返回的任务条目里取（不要从任务名推断） |
+| `task_id` | 可选 | string (UUID) | 任务 ID；不传则为模块级汇报 |
+| `content` | ✅ **必填** | string | 汇报内容（今日进展），支持 Markdown，可为空字符串 |
+| `progress_update` | 可选 | int (0-100) | 任务进度百分比（字段名是 `progress_update`，不是 `progress`） |

-| 字段 | 类型 | 说明 |
-|------|------|------|
-| `task_id` | string | 任务 ID（从待报任务中取） |
-| `content` | string | 汇报内容（今日进展） |
-| `progress` | int | 任务进度（0-100，整数） |
-| `status` | string | 可选，不改变则不传 |
+⚠️ **历史踩坑**：曾用错的字段名 `progress`、`status`，以及遗漏 `module_id`，会触发"参数缺失"错误。

 ---

@@ -33,12 +35,18 @@ Step 1: 展示待汇报任务列表，引导用户逐一填写内容
        └─────────────────────────────────────────

 Step 2: 收集所有填写内容，构建 items 数组
+        ⚠️ 每个 item 必须含 module_id（来自 Step 0 的任务条目）

 Step 3: [可选] 若用户请求 AI 辅助 → mcp__huanxi__llm_polish_report(content)
        将润色建议展示给用户，由用户确认采用哪个版本

 Step 4: mcp__huanxi__report_save_draft(items=[
-          { task_id: "xxx", content: "...", progress: 80 },
+          {
+            module_id: "<从任务条目取>",
+            task_id:   "<从任务条目取>",
+            content:   "今日完成 ...",
+            progress_update: 80
+          },
          ...
        ])

@@ -50,7 +58,7 @@ Step 5: 告知保存结果：

 ## 注意事项

- `progress` 是 **整数百分比**（0-100），不是小数
+- `progress_update` 是 **整数百分比**（0-100），不是小数；字段名末尾必须是 `_update`
 - 用户未填写 `content` 的任务：询问是否 dismiss（今天不汇报）还是暂时跳过
 - `report_save_draft` 是 upsert 操作，多次调用不会重复创建
 - 草稿保存成功后，下次调用 `report_get_today()` 可看到 draft 状态
@@ -1,5 +1,7 @@
 # 提交日报（+submit）

+> ⚠️ 参数细节以 MCP `report_submit_item` / `report_get_today` 的 docstring 为准，本文档仅做工作流引导。
+
 ## 前置条件

 - 草稿已通过 `report_save_draft()` 保存
@@ -23,7 +23,7 @@ description: "寰汐 MCP 共享基础：本地缓存策略（me/modules/users/wo

 | 文件 | 内容 | TTL | 刷新方式 |
 |------|------|-----|---------|
-| `me.json` | 当前用户身份（user_id, name, feishu_user_id） | 永久 | 手动删除文件 |
+| `me.json` | 当前用户身份（id, name, feishu_user_id；注意字段名是 `id` 而不是 `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） | 已有日期不重新查 |
@@ -37,6 +37,8 @@ description: "寰汐任务管理：创建任务（+create）、更新任务状

 ## +update：更新任务

+> ⚠️ 参数细节以 MCP `task_update` 的 docstring 为准，本节仅做工作流引导。
+
 ```
 Step 1: 确认任务 ID
        → 若用户已提供 task_id：直接使用
@@ -48,17 +50,24 @@ Step 1: 确认任务 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"
+          title?           : "新标题",
+          description?     : "新描述",
+          progress?        : 80,         ← 0-100 整数
+          progress_before? : 60,         ← 修改 progress 时必传当前值（乐观锁，防并发覆盖）
+          status?          : "not_started" | "in_progress" | "done" | "cancelled" | "on_hold",
+          end_date?        : "YYYY-MM-DD",  ← 字段名是 end_date，不是 due_date
+          priority?        : "low" | "medium" | "high" | "critical"
        })

 Step 4: 告知更新结果
 ```

+⚠️ **历史踩坑**：
+- 字段名 `due_date` 错误，后端为 `end_date`
+- 状态值 `todo` 错误，后端为 `not_started`
+- priority 缺 `critical`，没有 `urgent`
+- 改 progress 不传 `progress_before` 会 409 冲突
+
 ---

 ## +assign：设置执行人
@@ -1,17 +1,21 @@
 # 创建任务（+create）

+> ⚠️ 参数细节以 MCP `task_create` 的 docstring 为准，本文档仅做工作流引导。
+
 ## 必填信息收集

 在调用 `task_create` 前，引导用户提供：

 | 字段 | 必填 | 说明 |
 |------|------|------|
-| `module_id` | ✅ | 所属模块（从缓存解析名字 → ID） |
+| `module_id` | ✅ | 所属模块 UUID（从缓存解析名字 → ID） |
 | `title` | ✅ | 任务标题（简洁明了）|
-| `description` | 可选 | 任务详情、背景、验收标准 |
-| `due_date` | 可选 | 截止日期（YYYY-MM-DD 格式）|
-| `priority` | 可选 | `low` / `medium` / `high` / `urgent`，默认 medium |
-| `assignee_ids` | 可选 | 执行人（从缓存解析人名 → user_id）|
+| `description` | 可选 | 任务详情、背景、验收标准（Markdown） |
+| `end_date` | 可选 | 截止日期（YYYY-MM-DD 格式，**字段名是 end_date，不是 due_date**） |
+| `priority` | 可选 | `low` / `medium` / `high` / `critical`，默认 `medium`（**没有 urgent**） |
+| `status` | 可选 | `not_started`（默认）/ `in_progress` |
+| `parent_task_id` | 可选 | 父任务 UUID，传此字段即为子任务 |
+| `assignee_ids` | 可选 | 执行人 user_id 列表，**可在创建时一并传入**（无需再单独调 `task_set_assignees`） |

 ---

@@ -22,21 +26,23 @@ Step 1: 解析模块名 → module_id
  → Read ~/.claude/huanxi-cache/modules.json
  → 模糊匹配模块名（详见 huanxi-org resolve-ids.md）

-Step 2: [若用户提到执行人] 解析人名 → user_id
+Step 2: [若用户提到执行人] 解析人名 → user_id（user 对象的 id 字段）
  → Read ~/.claude/huanxi-cache/users.json
  → 未命中 → mcp__huanxi__user_list(name=<人名>) → 追加写缓存

-Step 3: 创建任务
+Step 3: 创建任务（推荐一次性把执行人也带上）
  → mcp__huanxi__task_create(
-      module_id   = "<模块ID>",
-      title       = "任务标题",
-      description = "...",       ← 可选
-      due_date    = "YYYY-MM-DD", ← 可选
-      priority    = "medium"      ← 可选
+      module_id     = "<模块ID>",
+      title         = "任务标题",
+      description   = "...",         ← 可选
+      end_date      = "YYYY-MM-DD",  ← 可选；字段名 end_date
+      priority      = "medium",      ← 可选；low/medium/high/critical
+      status        = "not_started", ← 可选；默认 not_started
+      assignee_ids  = ["<user_id>"]  ← 可选；若 Step 2 有解析到，建议一并传入
    )
  → 返回：task_id

-Step 4: 设置执行人（若 Step 2 有解析到）
+Step 4: [仅当 Step 3 未传 assignee_ids 时] 单独设置执行人
  → mcp__huanxi__task_set_assignees(
      task_id      = "<刚创建的 task_id>",
      assignee_ids = ["<user_id>"]
@@ -67,3 +73,14 @@ mcp__huanxi__task_create(
  parent_task_id = "<父任务ID>"   ← 传此字段即为子任务
 )
 ```
+
+---
+
+## 字段名速查（避免漂移）
+
+| 概念 | 正确字段名 | 错误写法 |
+|------|----------|---------|
+| 截止日期 | `end_date` | ~~due_date~~ |
+| 紧急优先级 | `critical` | ~~urgent~~ |
+| 未开始状态 | `not_started` | ~~todo~~ |
+| 父任务 ID | `parent_task_id` | ~~parent_id~~（后端 body 内是 parent_id，但 MCP 参数是 parent_task_id） |
@@ -1,22 +1,27 @@
 # 任务看板（+board）

+> ⚠️ 参数细节以 MCP `task_list_mine` / `task_list_by_module` / `people_get_board` 的 docstring 为准，本文档仅做工作流引导。
+
 ## 查看我的任务

 ```
 Step 1: mcp__huanxi__task_list_mine()
        → 返回我认领的所有任务（跨模块）
+        → 每条含：id / title / status / priority / progress / module_name / end_date / assignees

-Step 2: 按状态分组展示：
+Step 2: 按状态分组展示（状态值与后端枚举一致）：
        ────────────────────────────────────
-        📋 待处理（todo）
-          · [前端开发] 完成登录页面 UI 优化  ← 截止: 04-15
+        📋 未开始（not_started）
+          · [前端开发] 完成登录页面 UI 优化  ← end_date: 04-15
          · [后端API]  接口文档更新           ← 无截止日

        🔄 进行中（in_progress）
-          · [前端开发] 接口联调  60%          ← 截止: 04-20
+          · [前端开发] 接口联调  60%          ← end_date: 04-20

        ✅ 已完成（done）
          · [前端开发] 初始化项目结构  100%
+
+        ⏸️ 已挂起（on_hold） / ❌ 已取消（cancelled）— 默认折叠
        ────────────────────────────────────
 ```

@@ -47,5 +52,5 @@ Step 2: 展示每人的任务负载情况（适合分配任务前参考）
 |------|------|
 | "我今天要做什么" | task_list_mine() → 过滤 status=in_progress + 截止日临近 |
 | "某个模块的任务" | task_list_by_module(module_id) |
-| "即将到期的任务" | task_list_mine() → 筛选 due_date ≤ 今日+3天 |
+| "即将到期的任务" | task_list_mine() → 筛选 end_date ≤ 今日+3天 |
 | "团队任务分布" | people_get_board() |
@@ -1,5 +1,7 @@
 # 周报草稿（+draft，仅限模块负责人）

+> ⚠️ 参数细节以 MCP `weekly_report_save` 的 docstring 为准，本文档仅做工作流引导。
+
 ## 数据来源

 周报草稿基于**本周负责人日报汇总**（`leader_report_get_batch` 返回值），而非员工个人日报。
@@ -34,8 +36,8 @@ Step 4: 展示草稿给用户审阅修改
 Step 5: 用户确认后逐模块保存：
        mcp__huanxi__weekly_report_save(
          module_id      = "<模块ID>",
-          year           = <ISO year>,   ← 注意：ISO year，不是日历年
-          week           = <ISO week>,
+          year           = <ISO year>,    ← 注意：ISO year，不是日历年
+          week_number    = <ISO week>,    ← 后端字段名是 week_number，不是 week
          content        = "<本周总结>",
          next_week_plan = "<下周计划>"
        )