Add weekly-req-progress skill
把本周工作沉淀进团队共享的飞书「需求进度」多维表格的 skill: 按当前登录用户匹配相关需求行置顶追加进展/下周计划/阻碍, 无匹配则新建需求行,需求衍生的 bug/子任务建子记录,写前 --dry-run 预览确认。 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
commit
c22a511fe3
26
README.md
Normal file
26
README.md
Normal file
@ -0,0 +1,26 @@
|
||||
# agent-team-skills
|
||||
|
||||
团队通用的 Claude Code / agent skills 集合。每个子目录是一个独立 skill(含 `SKILL.md` + 可选 `scripts/`、`references/`)。
|
||||
|
||||
## 安装
|
||||
|
||||
把需要的 skill 目录放到本机 `~/.claude/skills/` 下即可被 Claude Code 自动发现:
|
||||
|
||||
```bash
|
||||
git clone https://gitea.d-robotics.cc/junjie.ding/agent-team-skills.git
|
||||
cp -R agent-team-skills/weekly-req-progress ~/.claude/skills/
|
||||
```
|
||||
|
||||
之后在对话里说出对应触发语,Claude 会自动调用。
|
||||
|
||||
## skills 一览
|
||||
|
||||
| skill | 作用 | 触发示例 |
|
||||
|---|---|---|
|
||||
| [`weekly-req-progress`](weekly-req-progress/) | 把本周和 agent 聊过/做过的工作沉淀进团队共享的飞书「需求进度」多维表格:按当前登录用户匹配相关需求行,置顶追加【本周】进展 /【下周】计划 / 阻碍;没匹配的需求新建一行;需求衍生的 bug/子任务建子记录。写前先 `--dry-run` 预览确认。 | "基于这周聊的,更新我的需求进展和下周计划" |
|
||||
|
||||
## 约定
|
||||
|
||||
- skill 名用小写短横线(kebab-case)。
|
||||
- 涉及飞书操作的 skill 依赖本机已安装并登录的 `lark-cli`(见各 skill 的 `references/`)。
|
||||
- 谁运行就以谁的飞书身份操作(`lark-cli auth status`),不写死个人,方便全团队复用。
|
||||
90
weekly-req-progress/SKILL.md
Normal file
90
weekly-req-progress/SKILL.md
Normal file
@ -0,0 +1,90 @@
|
||||
---
|
||||
name: weekly-req-progress
|
||||
description: >-
|
||||
把"本周和 agent 聊过/做过的工作"沉淀进团队共享的飞书「需求进度」多维表格——按当前登录用户(负责人)
|
||||
匹配到相关需求行,置顶追加【本周】进展、【下周】计划和阻碍;没有匹配的需求就新建一行;需求衍生的 bug/子任务
|
||||
就在该需求下建子记录。只要用户说到"更新我的需求进展/进度""更新进度表""同步本周做的到需求表""周五/周末
|
||||
收尾整理进展""下周计划""记录阻碍""写周报前把进度填进飞书表"之类,即使没明说"飞书"或表名,也应触发本 skill。
|
||||
写入前一定先给用户看改动预览、确认后再写(共享表)。
|
||||
---
|
||||
|
||||
# 需求进度周更
|
||||
|
||||
把这一周的工作沉淀进**团队共享**的飞书「需求进度」多维表格。表的硬信息(base_token、字段 id、选项、
|
||||
CellValue 写法、格式样例)全在 [`references/table-schema.md`](references/table-schema.md)——执行到写入相关步骤前先读它。
|
||||
|
||||
前置依赖:`lark-base` skill(Base 命令族)、`lark-shared`(身份与权限)。本 skill 只负责"周更"这套编排。
|
||||
|
||||
## 为什么这么设计
|
||||
|
||||
- **共享表,多人共用**:表里有很多同事的行。本 skill 给全团队用,所以"我是谁"靠 `lark-cli auth status`
|
||||
动态取当前登录用户,而**不是写死某个人**;全程只动"我负责"的行,绝不碰别人的行。
|
||||
- **置顶累加而非覆盖**:进展/计划/阻碍都是按"一段一周、最新放最上面"维护,保留历史轨迹,方便日后回溯写周报。
|
||||
所以写法永远是"读现值 → 新块拼在最前 → 写回",绝不直接覆盖。
|
||||
- **先预览再落库**:共享数据出错代价大,所以写之前先把"要改哪些行、加什么块、建什么新行"摊给用户确认。
|
||||
|
||||
## 流程
|
||||
|
||||
按顺序走。Step 3 起涉及表操作,开始前先把 `references/table-schema.md` 读进来。
|
||||
|
||||
### Step 0 · 认领身份
|
||||
跑 `lark-cli auth status`,取 `userOpenId` 和 `userName`——这就是"我"。后续匹配/写入全部围绕这个 open_id。
|
||||
- 若返回 token 失效/未登录,引导用户先 `lark-cli auth login --domain base`,再继续。
|
||||
- 记住这个 open_id,新建行的 `负责人`/`需求提出人` 也用它。
|
||||
|
||||
### Step 1 · 梳理本周工作
|
||||
从**当前对话**里归纳这周用户做了/聊了什么,拆成几个离散主题(一个主题大概对应一行需求)。
|
||||
- agent 只看得到当前会话。如果本会话内容不足以覆盖"这一周",**主动让用户补一句**这周还干了啥、或贴一下要点,
|
||||
别凭空编。
|
||||
- 每个主题先想清楚三件事:**本周进展**、**下周计划**、**当前阻碍**(没有就留空)。
|
||||
|
||||
### Step 2 · 算周期标记
|
||||
```bash
|
||||
python3 scripts/week_range.py
|
||||
```
|
||||
(脚本路径相对本 skill 目录。)拿到 `this_week.marker`(用于进展/阻碍)和 `next_week.marker`(用于下周计划),
|
||||
以及 `today_datetime`(新建行写开始日期用)。需要为别的日期算时传 `--date YYYY-MM-DD`。
|
||||
|
||||
### Step 3 · 读"我的行"
|
||||
`lark-cli base +record-list`(串行,`--limit 200`,看 `has_more`)读全表,建两份索引:
|
||||
1. **我的需求行**:`负责人` 含我 open_id 的行 → 记 `record_id / 需求名称 / 项目名称 / 父记录 / 状态` 及现有
|
||||
进展/下周计划/阻碍 文本(后面要拼接,需要现值)。
|
||||
2. **可选父节点**:被其它行用 `父记录` 指向过的行 = 现有分组/父节点候选(新建需求时推荐归属用)。
|
||||
|
||||
### Step 4 · 匹配并规划(先攒计划,不写)
|
||||
把每个主题映射成一个动作:
|
||||
- **命中已有需求行** → 计划在该行 `进展描述`/`下周计划`/`阻碍` 顶部追加对应块。
|
||||
- **是某需求衍生的 bug 修复 / 子任务** → 计划**新建一条子记录**,`父记录` 指向命中的需求行(见 schema 第 6 节)。
|
||||
- **没有任何匹配** → 计划**新建一行需求**:`需求名称`(详细)、`项目名称`(短标签)、`状态`、`优先级`、`需求来源`、
|
||||
`负责人`=我、`需求提出人`=我、`开始日期`=今天,并**推荐一个 `父记录` 分组**(评测系统 / 基础设施 / 运营 等,
|
||||
从 Step 3 的候选里挑最贴切的),由用户确认;用户说"先不挂"就建顶层需求。
|
||||
|
||||
文本块按 schema 第 3 节格式:块内换行用 `\n`,块间用 `\n\n`(真实换行,写在 `--json` 里就是 JSON 转义 `\n`/`\n\n`;
|
||||
**别写 `<br>`**),新块置顶。
|
||||
**幂等**:拼接前检查现值开头是否已有"本周同一标记"的块;有就合并/替换那个块,别再加一个(schema 第 4 节)。
|
||||
|
||||
### Step 5 · 预览 + 确认 ⛔(写入前必经)
|
||||
给用户一份清楚的预览,**等用户确认或改完再往下写**:
|
||||
- 概览:将**更新 N 行 / 新建 M 行需求 / 建 K 条子任务**。
|
||||
- 每个更新行:行名 + 即将置顶的新块原文(三类分别列)。
|
||||
- 每条新记录:完整字段值(含拟定的父节点)。
|
||||
- 可对每条拟写命令加 `--dry-run` 跑一遍,把将发的请求一并贴给用户看。
|
||||
允许用户逐条增删改、调整归属、改措辞。用户没点头不要写。
|
||||
|
||||
### Step 6 · 写入
|
||||
按 schema 第 6 节执行,全程 `--as user`:
|
||||
- **更新行**:先按 schema 第 5 节 `+record-get --format json` 读出该行精确现值 → 内存里拼"新块 `\n\n` 旧内容"
|
||||
→ `+record-upsert --json '{...}'`(按 record_id)。绝不覆盖、绝不漏掉旧内容。**只写我负责的行。**
|
||||
- **新需求 / 子任务**:`+record-batch-create --json '{"records":[{"fields":{...}}]}'`。
|
||||
- 串行写,批次间隔 0.5–1s;文本块用 `\n`/`\n\n`,select 用现网选项名,user 用 `[{"id":"ou_…"}]`,
|
||||
link 用 `[{"id":"rec…"}]`,datetime 用 `"YYYY-MM-DD HH:mm:ss"`。
|
||||
- 报 `91403` 不重试,按 `lark-shared` 引导处理权限。
|
||||
|
||||
### Step 7 · 回报
|
||||
汇总实际改了哪些行、建了哪些新行/子任务。需要时用 `+record-share-link-create` 给出记录链接,方便用户核对。
|
||||
|
||||
## 红线
|
||||
- 只动当前登录用户负责的行;别人的行只读不写。
|
||||
- 文本字段永远读-拼-写,不覆盖;幂等防重复【本周】块。
|
||||
- 写前必预览确认。
|
||||
- 选项值不在现网就提示用户,别擅自新增选项。
|
||||
159
weekly-req-progress/references/table-schema.md
Normal file
159
weekly-req-progress/references/table-schema.md
Normal file
@ -0,0 +1,159 @@
|
||||
# 「需求进度」表结构与写入规范
|
||||
|
||||
本文件固化目标表的硬信息和写入约定。SKILL.md 的流程引用本文件。
|
||||
前置:操作前先读 `lark-base` skill(命令族与执行规则)和 `lark-shared`(身份/权限)。
|
||||
|
||||
## 1. 目标定位(稳定值)
|
||||
|
||||
- wiki: `https://horizonrobotics.feishu.cn/wiki/Pu1iwvKmViRITbkXZWNcSHVNnXc?table=tbltaq90Bzk3AZv7&view=vewVouNuUH`
|
||||
- `base_token = XvR1bLZoXamRzdsnTWvcoMslnSb`
|
||||
- `table_id = tbltaq90Bzk3AZv7`
|
||||
- 所有命令统一带 `--base-token XvR1bLZoXamRzdsnTWvcoMslnSb --table-id tbltaq90Bzk3AZv7 --as user`。
|
||||
- 写命令都支持 `--dry-run`(只打印将发的请求、不落库)——预览阶段就用它。
|
||||
|
||||
万一表迁移导致 token 失效,用 wiki 链接重解析(取 `obj_token`,`obj_type` 应为 `bitable`):
|
||||
```bash
|
||||
lark-cli wiki spaces get_node --params '{"token":"Pu1iwvKmViRITbkXZWNcSHVNnXc"}' --as user
|
||||
```
|
||||
然后 `lark-cli base +field-list ...` 重新核对字段 id(字段 id 也可能变)。
|
||||
|
||||
## 2. 字段一览
|
||||
|
||||
| 字段名 | id | 类型 | 可写 | 说明 |
|
||||
|---|---|---|---|---|
|
||||
| 需求名称 | fldDdAHOi1 | text | ✅ | 主字段,需求的详细名称 |
|
||||
| 项目名称 | fld8uqlZ31 | text | ✅ | 短标签/分组名(如"培训""产品采购") |
|
||||
| 进展描述 | fldpIlI3iG | text | ✅ | 置顶累加【本周】块 |
|
||||
| 下周计划 | fldWoZtOGB | text | ✅ | 置顶累加【下周】块 |
|
||||
| 阻碍 | fldfMuEc67 | text | ✅ | 置顶累加【本周】块 |
|
||||
| 状态 | fldY5QX71W | select 单选 | ✅ | 待启动 / 进行中 / 已完成 / 暂停 |
|
||||
| 优先级 | fldCfj2LmG | select 单选 | ✅ | P0 / P1 / P2 / P3 |
|
||||
| 需求来源 | fldAN4v6VR | select 多选 | ✅ | 内部 / 外部 / 客户 / evb团队、B端客户 |
|
||||
| 负责人 | fldKxguQI1 | user 多选 | ✅ | **用它界定"我的行"** |
|
||||
| 需求提出人 | fldpQACWmg | user 多选 | ✅ | |
|
||||
| 父记录 | fldprd19G7 | link(自关联本表) | ✅ | 子任务/层级机制 |
|
||||
| 开始日期 | fldwkxLk0S | datetime | ✅ | 显示 yyyy/MM/dd |
|
||||
| 预计完成 | fldkDnTzum | datetime | ✅ | |
|
||||
| 实际完成 | fldI2fLZgL | datetime | ✅ | |
|
||||
| 备注 | fld41vLVFs | text | ✅ | |
|
||||
|
||||
写前务必 `lark-cli base +field-list ... --as user` 现取一次,核对 id 与选项未变(以现网返回为准,别信任本表写死的 id)。
|
||||
|
||||
## 3. 文本块格式:置顶累加(真实换行,不是 `<br>`)
|
||||
|
||||
进展描述 / 下周计划 / 阻碍 三个 text 字段都按"一段一周、最新置顶"维护。
|
||||
|
||||
- 块标记由 `scripts/week_range.py` 产出:进展/阻碍用 `本周` 标记,下周计划用 `下周` 标记。
|
||||
- **存储用真实换行符**:块内换行 = 一个换行 `\n`,块与块之间 = 空行 `\n\n`。
|
||||
(现网真实存储就是 `\n`/`\n\n`;之前在表格视图里看到的 `<br>` 只是列表渲染对换行的转义,**别往字段里写 `<br>`**。)
|
||||
- 在 `--json '{...}'` 命令里,按 JSON 规范写转义 `\n`/`\n\n` 即可——CLI 的 JSON 解析会把它变成真实换行(已实测 `--dry-run` 验证)。
|
||||
- **新块永远拼在最前面(最上方)**,旧内容原样保留在后面。
|
||||
|
||||
单个块(JSON 字符串内):
|
||||
```
|
||||
【YYYY/MM/DD ~ MM/DD 本周】\n1. 第一件事\n2. 第二件事
|
||||
```
|
||||
|
||||
字段最终值(新块 + 旧内容):
|
||||
```
|
||||
<新块>\n\n<字段原有内容>
|
||||
```
|
||||
|
||||
### 现网真实样例(进展描述,已是最新置顶)
|
||||
```
|
||||
【2026/05/25 ~ 05/29 本周】\n1. WorkBuddy 培训安排会…\n2. Agent catch-up 分享…\n\n【2026/05/18 ~ 05/22 本周】\n1. AI 培训沟通对齐…
|
||||
```
|
||||
|
||||
### 阻碍块
|
||||
和进展同样用 `本周` 标记、置顶累加、保留历史。已解决的旧阻碍**不删**,保留轨迹(用户已确认):
|
||||
```
|
||||
【2026/06/01 ~ 06/05 本周】\nllmgateway 日志权限还没拿到,暂时无法坐实中转链路
|
||||
```
|
||||
|
||||
## 4. 幂等:防重复块
|
||||
|
||||
写之前先看目标字段现值是否**已经含有"本周同一周期标记"的块**(即 `week_range.py` 算出的本周 marker 已出现在字段开头)。
|
||||
- 已存在 → 把内容**合并进那个已有块 / 替换该块**,不要再加一个同周期块。
|
||||
- 不存在 → 正常置顶新增。
|
||||
|
||||
这样同一个周五重复跑、或一周内多次更新,都不会堆出多个【本周】。
|
||||
|
||||
## 5. 读取现值(拼接前必做)
|
||||
|
||||
更新文本字段必须先拿到**精确的当前字符串**才能把新块拼到前面。`+record-get --format json` 是按列存的:
|
||||
`data.field_id_list` 是列顺序,`data.data[0]` 是该行各列的值(与 `field_id_list` 同序)。用一行 python 取某字段原文:
|
||||
|
||||
```bash
|
||||
lark-cli base +record-get --base-token XvR1bLZoXamRzdsnTWvcoMslnSb --table-id tbltaq90Bzk3AZv7 \
|
||||
--record-id recXXXX --as user --format json \
|
||||
| python3 -c "import sys,json; d=json.load(sys.stdin)['data']; \
|
||||
print(d['data'][0][d['field_id_list'].index('fldpIlI3iG')] or '')"
|
||||
```
|
||||
(把 `fldpIlI3iG` 换成 进展描述/下周计划/阻碍 对应 id。)`+record-list --format json` 同样是列式:
|
||||
`data.fields`(列名) / `data.field_id_list` / `data.data`(行) / `data.record_id_list`(与行同序) / `data.has_more`。
|
||||
|
||||
## 6. CellValue 写法(按字段类型)
|
||||
|
||||
`+record-upsert --json` / `+record-batch-create --json` 里 `fields` 用「字段名→值」:
|
||||
|
||||
- text:字符串;多行块用 `\n` / `\n\n`(JSON 转义)拼好。
|
||||
- select 单选(状态/优先级):选项名字符串,如 `"进行中"`、`"P1"`。
|
||||
- select 多选(需求来源):字符串数组,如 `["内部"]`。
|
||||
- user(负责人/需求提出人):`[{"id":"ou_xxx"}]`(open_id 数组)。
|
||||
- link(父记录):`[{"id":"recXXXX"}]`(父行 record_id 数组)。
|
||||
- datetime(开始日期等):字符串 `"YYYY-MM-DD HH:mm:ss"`,如 `"2026-06-01 00:00:00"`(`week_range.py` 的 `today_datetime` 可直接用)。别传相对时间,否则报 1254064。
|
||||
|
||||
只写存储字段(上表"可写"列)。
|
||||
|
||||
### 更新已有行(置顶追加)
|
||||
`+record-upsert` 用 `--json`(不是 `--fields`),按 `record_id` 定位:
|
||||
```bash
|
||||
# 1) 先按第 5 节读出该行 进展描述/下周计划/阻碍 的现值
|
||||
# 2) 内存里拼好"新块 \n\n 旧内容",先 --dry-run 看请求,再去掉 --dry-run 落库
|
||||
lark-cli base +record-upsert --base-token XvR1bLZoXamRzdsnTWvcoMslnSb --table-id tbltaq90Bzk3AZv7 \
|
||||
--record-id recXXXX --as user \
|
||||
--json '{"进展描述":"<新本周块>\n\n<旧进展>","下周计划":"<新下周块>\n\n<旧计划>","阻碍":"<新阻碍块>\n\n<旧阻碍>"}'
|
||||
```
|
||||
|
||||
### 新建需求行
|
||||
`+record-batch-create --json '{"records":[{"fields":{...}}]}'`:
|
||||
```bash
|
||||
lark-cli base +record-batch-create --base-token XvR1bLZoXamRzdsnTWvcoMslnSb --table-id tbltaq90Bzk3AZv7 \
|
||||
--as user --json '{"records":[{"fields":{
|
||||
"需求名称":"<详细名>","项目名称":"<短标签>",
|
||||
"状态":"进行中","优先级":"P1","需求来源":["内部"],
|
||||
"负责人":[{"id":"ou_当前用户"}],"需求提出人":[{"id":"ou_当前用户"}],
|
||||
"开始日期":"2026-06-01 00:00:00",
|
||||
"进展描述":"<本周块>","下周计划":"<下周块>",
|
||||
"父记录":[{"id":"rec分组行"}]
|
||||
}}]}'
|
||||
```
|
||||
`父记录` 可省略(建为顶层需求)。
|
||||
|
||||
### 新建子任务(需求衍生的 bug/子任务)
|
||||
和新建行同命令,关键是 `父记录` 指向命中的需求行;子任务自己也带进展/状态:
|
||||
```bash
|
||||
--json '{"records":[{"fields":{
|
||||
"需求名称":"<bug/子任务名>","状态":"进行中","优先级":"P2",
|
||||
"负责人":[{"id":"ou_当前用户"}],
|
||||
"父记录":[{"id":"rec命中的需求"}],
|
||||
"进展描述":"<本周块>"
|
||||
}}]}'
|
||||
```
|
||||
|
||||
## 7. 选父节点(新建需求时)
|
||||
|
||||
新需求归属**不固定**于 AI-Native 树,可能是评测系统等别的分组。做法:
|
||||
1. `+record-list` 读全表,找出"被别的行用 `父记录` 指向过"的行 = 现有分组/父节点候选;
|
||||
2. 根据内容推荐最贴切的一个父节点,**让用户确认**;
|
||||
3. 用户认可才写 `父记录`;用户说"先不挂"就建顶层需求。
|
||||
|
||||
不要自己新建分组行,除非用户明确要求。
|
||||
|
||||
## 8. 读写注意(来自 lark-base 规则)
|
||||
|
||||
- list 类命令(`+record-list` / `+field-list`)串行执行,别并发。
|
||||
- `+record-list --limit` 最大 200;先读首批看 `has_more`。
|
||||
- 批量写单批 ≤ 200;连续写同表串行 + 批次间隔 0.5–1s。
|
||||
- 权限报 `91403` 不要重试,按 `lark-shared` 流程引导。
|
||||
- 选项值(状态/优先级/需求来源)必须用现网已有选项名;想用的值不存在时**提示用户**,不要擅自新增选项。
|
||||
63
weekly-req-progress/scripts/week_range.py
Executable file
63
weekly-req-progress/scripts/week_range.py
Executable file
@ -0,0 +1,63 @@
|
||||
#!/usr/bin/env python3
|
||||
"""计算「需求进度」表里用的周期标记。
|
||||
|
||||
进展描述 / 阻碍 用「本周」块,下周计划 用「下周」块,格式固定为:
|
||||
【YYYY/MM/DD ~ MM/DD 本周】
|
||||
【YYYY/MM/DD ~ MM/DD 下周】
|
||||
起始为周一(整周第一天)、结束为周五,跨月时结束也只写 MM/DD。
|
||||
|
||||
把"今天是星期几、本周/下周哪天到哪天"交给脚本算,避免每次人肉推算出错。
|
||||
|
||||
用法:
|
||||
python week_range.py # 用今天
|
||||
python week_range.py --date 2026-06-01
|
||||
输出 JSON,字段见下方 build()。
|
||||
"""
|
||||
import argparse
|
||||
import datetime
|
||||
import json
|
||||
|
||||
|
||||
def build(today: datetime.date) -> dict:
|
||||
# weekday(): 周一=0 ... 周日=6。回退到本周一。
|
||||
monday = today - datetime.timedelta(days=today.weekday())
|
||||
friday = monday + datetime.timedelta(days=4)
|
||||
next_monday = monday + datetime.timedelta(days=7)
|
||||
next_friday = next_monday + datetime.timedelta(days=4)
|
||||
|
||||
def marker(start: datetime.date, end: datetime.date, label: str) -> str:
|
||||
# 起始写完整年月日,结束只写月日(与表内既有数据一致)
|
||||
return f"【{start:%Y/%m/%d} ~ {end:%m/%d} {label}】"
|
||||
|
||||
return {
|
||||
"today": today.isoformat(),
|
||||
"this_week": {
|
||||
"monday": monday.isoformat(),
|
||||
"friday": friday.isoformat(),
|
||||
"marker": marker(monday, friday, "本周"),
|
||||
},
|
||||
"next_week": {
|
||||
"monday": next_monday.isoformat(),
|
||||
"friday": next_friday.isoformat(),
|
||||
"marker": marker(next_monday, next_friday, "下周"),
|
||||
},
|
||||
# 给 datetime 字段写值时用(开始日期等需要 "YYYY-MM-DD HH:mm:ss")
|
||||
"today_datetime": f"{today:%Y-%m-%d} 00:00:00",
|
||||
}
|
||||
|
||||
|
||||
def main() -> None:
|
||||
parser = argparse.ArgumentParser(description="计算需求进度表的周期标记")
|
||||
parser.add_argument("--date", help="基准日期 YYYY-MM-DD,默认今天")
|
||||
args = parser.parse_args()
|
||||
|
||||
if args.date:
|
||||
today = datetime.date.fromisoformat(args.date)
|
||||
else:
|
||||
today = datetime.date.today()
|
||||
|
||||
print(json.dumps(build(today), ensure_ascii=False, indent=2))
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
main()
|
||||
Loading…
x
Reference in New Issue
Block a user