> SKILL_VERSION = v1.0.2（技能自身版本）
> 这是本技能在平台技能库中注册的版本号（platform_skills.version 字段），与后端 platform_skill 发版线治理流水号（version_changelog 表，如 V1.0.10）是两个独立体系，切勿混淆。
>
> - 技能自身版本（v1.0.2）：随技能包内容更新而递增，由 sync_skill_to_library.py 上传时指定
> - 发版线版本（V1.0.8 → V1.0.9 → V1.0.10）：全局递增计数器，每次登记操作记录时 +1 minor，summary 中须注明当时的技能库版本号

同事会智能填报 Skill

通过自然语言将今日工作总结提交到「同事会」工作简报系统，AI 自动拆分归类入库。

核心流程（必须按顺序执行）

第零步：首次运行引导（仅首次）

检测标记文件 ~/.workbuddy/skills/tongshihui-intake/.installed：
- 不存在 → 向用户输出一份「工作简报技能使用简述」（见下方模板），然后创建 .installed 标记文件（空文件即可），避免重复打扰
- 已存在 → 跳过本步

使用简述模板（首次输出给用户）：
> 📋 工作简报技能 · 使用说明
> 我是「工作简报」智能填报助手。你只需用自然语言告诉我今天做了什么，我会自动拆分归类并提交到同事会工作简报系统。
> 用法：直接说"帮我提交今天的简报：完成了XX、推进了YY"，或说"填报工作"即可触发。
> 首次使用需先扫码登录（微信扫小程序码授权，登录态本地保存约 8 小时，过期会自动提醒你重新扫码）。
> 提交的数据仅你自己可见（visibility=self），来源标记为 workbuddy-skill。

第一步：版本自检（非阻断，仅友好提示）

每次运行检查是否有新版本可用，绝不阻断当前操作：
1. 调用公开接口 GET {base_url}/api/v1/system/version?type=platform_skill 取发版线最新记录
2. 从返回的 data.summary 字段中提取括号内的技能库版本号（格式如 ...（技能库 v1.0.1）），与本地 SKILL_VERSION（v1.0.0）做比对
3. 若检测到服务器端记录的技能库版本 高于 本地：
- 仅一行轻提示："💡 工作简报技能有新版本（v{最新版本}），当前为 v{本地版本}。如需更新请重新下载安装：{下载链接}"
- 不报错、不阻断、不要求立即操作，本次仍按当前版本正常继续使用
4. 若版本一致或无法判断 → 静默继续，不输出任何内容

下载链接（无需登录即可下载技能包 zip，已验证可用）：

https://www.xiaoniao.online/api/v1/platform-skills/public/tongshihui-intake/download

> 返回最新版技能包 zip（Content-Type: application/zip），直接下载覆盖 ~/.workbuddy/skills/tongshihui-intake/ 目录即可完成更新。

版本号体系说明（避免混淆）：
- SKILL_VERSION（本文件头部声明，如 v1.0.0）= 技能自身版本 = 平台技能库 platform_skills.version
- 发版线版本（如 V1.0.10）= version_changelog 表中的治理流水号，用于记录"对技能做了什么操作"

第二步：身份验证（每次使用前必查）

优先提醒用户完成扫码登录，这是使用本 Skill 的前置条件。

1. 检查本地是否已有有效 token：
   - 读取 ~/.workbuddy/skills/tongshihui-intake/.auth_state（JSON 格式 {token, user_id, expires_at, base_url}）
   - 若文件不存在或 expires_at < 当前时间 → token 无效，进入扫码登录流程
   - JWT 真实过期校验（加固）：若 token 存在，本地 base64 解码 JWT payload 的 exp 字段（不验证签名，仅读过期时间），若 exp < 当前 Unix 时间戳 → 视为已过期，主动清除 .auth_state 并提示"登录已过期，请重新扫码"，进入扫码流程

2. 扫码登录流程（与后台 admin-console 登录使用同一套小程序码）：

GET {base_url}/api/v1/system/scan-ticket?source=workbuddy_skill
→ 返回 { ticket, qrPngBase64, hint, expireSeconds }
（必须带 source=workbuddy_skill，后端据此签发 8 小时 JWT；不带则按默认 2 小时）

• 向用户展示二维码：将 qrPngBase64（data:image/png;base64,...）渲染为图片展示给用户
• 同时显示 hint 文字提示（如"请用微信扫一扫，将直接打开小程序授权"）
• 告知用户：用微信扫该码 → 打开同事会小程序 → 点「开始授权」即可

3. 轮询扫码状态（每 2-3 秒一次，最多等待 5 分钟）：

GET {base_url}/api/v1/system/scan-status/{ticket}
→ 返回 { status: "pending"|"confirmed", token?, userId? }

• status === "confirmed" → 登录成功，提取 token 和 userId
• status === "pending" → 继续轮询
• 404 → ticket 过期，重新生成

4. 保存登录态：将 {token, user_id, expires_at, base_url} 写入 .auth_state 文件供后续复用

第三步：收集工作内容

身份验证通过后，引导用户用自然语言描述今日工作：

• 若用户已在消息中提供了工作内容描述 → 直接使用
• 若未提供 → 主动询问："请用自然语言描述你今天的工作内容，我会帮你提交到工作简报"
• 可接受单条或多条工作事项（内部合并为一次 intake 调用）
• 默认日期为今天，若用户指定了日期则使用用户指定的日期（格式 YYYY-MM-DD）

第四步：调用智能填报 API

POST {base_url}/api/intake
Authorization: Bearer {token}
Content-Type: application/json

{
  "raw": "{用户的工作内容原文}",
  "author": "{用户姓名，从登录态获取或让用户确认}",
  "date": "YYYY-MM-DD",           // 可选，默认今天
  "platform": "workbuddy-skill",   // 固定值，标识来源
  "info_block_ids": []             // 可选，一般不传（由 AI 自动分类）
}

响应格式：

{
  "count": 1,
  "created": [{
    "id": "123",
    "date": "2026-08-18",
    "author": "张三",
    "category": "产品研发",
    "content": "完成智能填报功能开发",
    "ai_status": "done|analyzing|failed",
    "tags": []
  }],
  "dashboard": { "overall_summary": "..." },
  "duplicate": false
}

第五步：反馈结果

向用户报告提交结果：

• 成功：展示创建的条目数、分类、AI 分析状态
• AI 分析中：告知用户后台正在分析，稍后可在后台查看完整结果
• 重复提交：告知检测到重复，未重复创建
• 失败：展示错误信息

错误处理

配置

base_url（API 地址）

默认值：https://www.xiaoniao.online

可通过以下方式覆盖：
1. 环境变量 TONGSHIHUI_API_BASE
2. .auth_state 文件中的 base_url 字段
3. 首次使用时询问用户

.auth_state 文件位置

~/.workbuddy/skills/tongshihui-intake/.auth_state

安全注意：此文件包含用户 token，不应提交到版本控制或分享给他人。

注意事项

1. 数据隔离：所有提交的数据以扫码登录的用户身份写入，仅该用户本人可见（visibility=self）
2. 防重复：同一用户 30 秒内相同内容不会重复创建
3. AI 分类：后端自动根据用户的信息块配置进行分类；无信息块时自动创建"通用"块兜底
4. Token 有效期约 8 小时（Skill 专属，实测 28800s）：扫码登录必须带 source=workbuddy_skill，后端据此签发 8 小时 JWT；后台管理扫码登录仍为 2 小时。过期后需重新扫码
5. 平台标识：所有通过本 Skill 提交的记录，source="skill"、source_platform="workbuddy-skill"，便于后台区分来源

验证记录

• 2026-08-18 端到端验证通过（开发者本人账号 id=34 实测）：
• 扫码登录：调用 /api/v1/system/scan-ticket?source=workbuddy_skill 生成小程序码 → 微信扫同一码 → 轮询 /api/v1/system/scan-status/{ticket} 至 confirmed → 拿到 JWT（有效期 8 小时，Skill 专属）
• 数据提交：POST /api/intake {raw, author, platform:"workbuddy-skill"} → 返回 id=2427
• 验证点：后端强制 visibility=self（仅本人可见）；author 被后端用 DB 真实姓名覆盖（强身份绑定，不信任前端传入）；source_platform=workbuddy-skill（后台可区分 Skill 来源）；AI 分类后台异步（ai_status=analyzing 后转 ready）

• 结论：Skill 工作流与后台 API 契约完全一致，可分发给其他 WorkBuddy 用户安装使用

• 2026-08-18 人性化健壮性三维度加固（开发者本人账号实测）：

• 维度1 登录过期自动提醒：原已有 expires_at 本地预判 + HTTP 401 重扫；实测无效 token 打 /api/intake 返回 HTTP 401（未写库），后端侧链路成立；新增 JWT payload exp 字段本地解码校验作为加固层
• 维度2 首次安装使用简述：新增「第零步：首次运行引导」，检测 .installed 标记，首次输出使用说明模板并落标记，避免重复打扰
• 维度3 技能自我更新提示：后端已存在公开接口 /api/v1/system/version?type=platform_skill 与 /api/v1/system/changelog?type=platform_skill（当时实测最新 V1.0.10）；新增「第一步：版本自检」（后经概念纠偏，SKILL_VERSION 改为技能自身版本 v1.0.0，仅比对平台技能库版本号，且改为非阻断提示）

• 同步更新 references/api.md（修正 Token 有效期为 Skill 专属 8h；登记版本自检两接口）；重新打包分发版 tongshihui-intake.zip（已排除 .auth_state 等登录态）

• 2026-08-18 概念纠偏 + 漏传补录 + 公开下载端点：

• 概念纠正：SKILL_VERSION 从 V1.0.10（发版线版本）改为 v1.0.0（技能自身版本），与 platform_skill 发版线治理流水号解耦。frontmatter 新增 version: "1.0.0" 字段供 sync 脚本读取
• 漏传补录：通过 POST /api/v1/platform-skills/import 上传技能包到平台技能库 → id=11, UUID=B5DCEF0D, version=v1.0.0，截图确认列表可见
• 规则软化：版本自检从"比对+可能阻断"改为仅一行轻提示+给下载链接，绝不阻断当前操作
• 公开下载端点：后端新增 GET /api/v1/platform-skills/public/{skill_name}/download（无需登录），已部署 V2.3.626 并实测 HTTP 200 返回 7366 bytes zip ✅；下载链接确认为 https://www.xiaoniao.online/api/v1/platform-skills/public/tongshihui-intake/download
• 发版线登记：platform_skill V1.0.11（serial=941, summary 含技能库版本号 v1.0.0）；backend V2.3.626（serial=942, 公开下载端点）