cawplan-coding-insights

CawPlan 编码洞察

初始化

cawplan skill check

工作流

根据用户的需求并行获取相关视图。单日查询使用 --date；时间范围查询使用 --from/--to。

如果用户没有提供提示词，或者仅调用 /cawplan-coding-insights，则默认显示当前用户今天的报告：

today="$(date +%F)"
cawplan session my-sessions --date "$today"
cawplan session user-human-inputs --date "$today"

使用此默认输出汇总用户今天的个人会话、费用、令牌数、变更文件，以及人工输入要点。

---

工作区概览

总费用、令牌数、活跃成员数：

cawplan session overview --from <YYYY-MM-DD> --to <YYYY-MM-DD>

每日趋势（费用和令牌数随时间变化）：

cawplan session trend --from <YYYY-MM-DD> --to <YYYY-MM-DD>

可用的报告日期（用于日期选择器）：

cawplan session dates

---

费用明细维度（整个工作区）

按成员：

cawplan session by-member --from <YYYY-MM-DD> --to <YYYY-MM-DD>

按 AI 模型（Claude Opus、Sonnet、Haiku 等）：

cawplan session by-model --from <YYYY-MM-DD> --to <YYYY-MM-DD>

按模型和令牌类型（输入 / 输出 / 缓存）：

cawplan session by-model-dimension --from <YYYY-MM-DD> --to <YYYY-MM-DD>

按 AI 编码 Agent（Claude Code、Cursor、Codex 等）：

cawplan session by-agent --from <YYYY-MM-DD> --to <YYYY-MM-DD>

按 Git 项目/仓库：

cawplan session by-project --from <YYYY-MM-DD> --to <YYYY-MM-DD>

按 CawPlan 产品（需要产品与仓库的映射关系）：

cawplan session by-product --from <YYYY-MM-DD> --to <YYYY-MM-DD>

所有明细命令都支持使用 --page-num 和 --page-size 分页。

---

成员视图

列出所有有数据的成员：

cawplan session members

查看单个成员的完整详情：

cawplan session member-detail --member <git-username>

个人会话深入分析（概览 + 会话列表）：

# First resolve your user_id if needed
cawplan users query --email <your-email>

cawplan session my-sessions --user-id <user_id> --from <YYYY-MM-DD> --to <YYYY-MM-DD>

个人提示词质量摘要：

cawplan session user-human-inputs --user-id <user_id> --from <YYYY-MM-DD> --to <YYYY-MM-DD>

---

产品资格（coding-insights 控制项）

cawplan products list 返回的每个产品都带有一个 controls 数组（例如 ["dashboard", "version-plans", "issues-suggestions", "knowledge", "test-suites", "coding-insights"]），用于标明该产品启用的功能。只有 controls 中包含 "coding-insights" 的产品才有编码会话数据；对于这项技能，其他所有产品都属于范围之外，绝不要对其调用 product-* 会话端点：

• 解析单个产品（cawplan products list --search "<name>"）：接受精确的可访问名称匹配（忽略首尾空格后不区分大小写）、唯一的简称/令牌前缀匹配，或用户明确确认的候选项。如果用户指定的产品不存在或匹配不明确，请列出候选项并询问用户指的是哪个产品；绝不要擅自替换成名称最接近但不唯一的产品。然后检查匹配产品的 controls 再进行查询。如果缺少 coding-insights，请告知用户该产品尚未启用编码洞察，并停止操作，不要调用 product-overview/product-trend 等端点。
• 构建团队名册或汇总（cawplan products list --product_line_id <id>，用于下文的团队提交缺口和团队费用汇总）：在合并 members.rds 或汇总费用之前，先移除 controls 中不含 coding-insights 的产品。不要将这些产品的研发成员标记为“尚未提交”，也不要将这些产品计入费用总额——它们本来就不会有会话数据。请说明排除了哪些产品以及排除原因，不要悄然排除。

---

产品范围视图

需要产品的 unique_id。先解析该值（并按照上述规则确认产品具有 coding-insights 控制项）：

cawplan products list --search "<product name>"

产品费用概览：

cawplan session product-overview --product-id <id> --from <YYYY-MM-DD> --to <YYYY-MM-DD>

产品每日趋势：

cawplan session product-trend --product-id <id> --from <YYYY-MM-DD> --to <YYYY-MM-DD>

产品按成员划分的明细：

cawplan session product-by-member --product-id <id> --from <YYYY-MM-DD> --to <YYYY-MM-DD>

产品按模型划分的明细：

cawplan session product-by-model --product-id <id> --from <YYYY-MM-DD> --to <YYYY-MM-DD>

产品提示词质量摘要：

cawplan session product-human-inputs --product-id <id> --from <YYYY-MM-DD> --to <YYYY-MM-DD>

---

人工输入（提示词质量）分析

工作区提示词摘要（类别、主题、质量）：

cawplan session human-input-summary --from <YYYY-MM-DD> --to <YYYY-MM-DD>

提示词质量评分分布：

cawplan session human-input-quality --from <YYYY-MM-DD> --to <YYYY-MM-DD>

按产品划分的提示词数量和质量：

cawplan session human-input-by-product --from <YYYY-MM-DD> --to <YYYY-MM-DD>

带筛选条件的分页提示词列表：

cawplan session human-inputs \
  --from <YYYY-MM-DD> --to <YYYY-MM-DD> \
  [--member <name>] \
  [--product <name>] \
  [--category <name>] \
  [--topic <name>] \
  [--q <search text>] \
  [--needs-review] \
  [--limit 25] [--offset 0]

---

会话对话深入分析

cawplan session conversation --entry-id <entry_id>

---

团队提交缺口（“谁还没提交”）

这里的“团队”指 CawPlan 产品线（cawplan product-lines ... — CLI 自己的 init 提示会直接显示“Select CawPlan Team”）。“编码提交”指上传的 AI 日报（cawplan-coding-commit），不是 git 提交。

成员名单直接来自团队的产品 — 无需按用户反向查询。products list --product_line_id 已返回每个产品的 members 对象，而 members.rds[]（该产品配置的研发/开发人员）就是预期应提交编码报告的人。

1. 将团队名称解析为 product_line_id（分页并在客户端按名称匹配，与 cawplan-product-report 的团队工作流相同）：

   cawplan product-lines list --page_size 100
   

   要求团队名称完全匹配（去除空白后不区分大小写）、唯一的简称/令牌前缀匹配，或用户明确确认列出的候选项。如果多个名称匹配，请用户消除歧义。如果没有唯一匹配项，请列出候选项并询问用户指的是哪个团队，而不是猜测最接近的名称。

2. 解析团队的产品，并使用同一响应构建成员名单：

   cawplan products list --product_line_id <product_line_id>
   

   首先剔除 controls 不包含 coding-insights 的产品（参见上文“产品资格”）— 说明剔除了哪些产品。然后合并剩余产品中的 members.rds[].user_id（显示时使用 first_name/last_name）— 这就是成员名单。如果某个剩余产品的 rds 列表为空，请明确说明：该产品仍可能发生实际编码活动，但此工作流没有可用于核对该产品的成员名单，因此其中的提交缺口不会被标记，而是直接不可见。

3. 按照此技能其他部分的相同方式解析目标日期（today="$(date +%F)"，或用户提供的确切日期/范围 — 不要传入字面字符串“today”）。查找该时间范围内实际提交的人 — 会话数据只会在有人运行 cawplan-coding-commit 上传流程后才存在（此 CLI 不会被动/自动收集数据），因此此处出现的 user_id 意味着该用户已提交，而不只是“处于活跃状态”：

   cawplan session product-sessions --product-id <pid> --date <date>
   # or --from/--to for a range
   

   对步骤 2 中的每个产品各运行一次 — 每条会话记录都直接包含 user_id，无需关联。合并所有结果中的 user_id — 这就是“已提交”集合。注意任何不在成员名单中的已提交 user_id，将其作为额外发现（有人在没有配置研发分工的情况下作出贡献）报告，而不是默默将其丢弃。

4. 求差集：成员名单（步骤 2）减去已提交集合（步骤 3）= 该时间范围内尚未提交的人。按姓名报告。

---

团队成本汇总

任何 session 成本命令都没有 product_line_id 参数 — 只有 --product-id。请自行汇总：

1. 按照“团队提交缺口”步骤 1–2 的相同方式解析团队的 product_line_id 和产品 — 继续之前，先剔除不包含 coding-insights 控制项的产品。
2. 对于每个剩余产品：

   cawplan session product-overview --product-id <pid> --from <YYYY-MM-DD> --to <YYYY-MM-DD>
   cawplan session product-by-model --product-id <pid> --from <YYYY-MM-DD> --to <YYYY-MM-DD>   # only if the user asked for a model breakdown
   

3. 汇总各产品的成本/令牌，得出总计。按模型细分时，汇总各产品中名称相同的模型，而不是逐个报告产品的表格，除非用户要求按产品查看。如果按模型汇总的总计与 product-overview 总计不一致（例如按模型分类的端点未归类某个模型分组），请同时报告两个数字，而不是默默选择其一 — 不要假设它们总能对上。

团队中每个产品需要调用一到两次 — 如果团队产品数量异常多，请说明调用次数；不过通常开销很低（受产品数量限制，而非工作区用户数量）。

成本/差异异常检测（“成本高、差异小”）

上传的报告会按会话记录 files_changed / files_added / files_deleted 以及成本——这有助于发现两者不成比例的会话。

1. 根据请求确定范围：
   • 某位成员 → 解析其 user_id（与“成员视图”相同：查询自己的信息时使用 auth status，查询其他成员时使用 users query --email/--keyword），然后运行 cawplan session my-sessions --user-id <user_id> --from <YYYY-MM-DD> --to <YYYY-MM-DD>。使用此命令，不要使用 session member-detail --member <git-username>——已通过实时验证：member-detail 的每会话记录包含 tokens，但完全没有 cost 字段，因此无法用于按成本排序；my-sessions 的记录则同时包含 cost 和 files_changed。
   • 某个产品 → 先按上文“产品资格”解析产品（如果其 controls 中没有 coding-insights，则跳过），然后运行 cawplan session product-sessions --product-id <id>（指定时间范围时添加 --from/--to）——已通过实时验证：其记录同时包含 cost 和 files_changed。
   • 整个工作区 → 运行 cawplan session members，然后针对每位成员运行 my-sessions --user-id <id>（不要使用 member-detail，原因与上面成员条目中缺少成本字段相同）——这确实需要遍历工作区中的所有成员，与“团队提交缺口”不同（后者直接从 products list 读取名册，而不是逐个用户查询）。告知用户调用次数，并在发出约 30 次以上调用前征得明确同意。
2. 不要臆造固定的成本或差异阈值（例如“成本 > $50”）——你并不知道组织的正常范围。应按成本降序、按 files_changed 升序排列获取到的会话，并重点展示在这两个方向上都明显突出的会话——结果集较小时（约少于 10 个会话），不要强行套用严格的四分位数界限，因为这可能仅因微小差距就机械地排除明显异常值；应将排序作为参考，标出突出的会话并展示其具体数值，同时说明被标记的会话是否仅略低于严格的四分位数界限。说明标记结果是相对于获取到的数据集而言，并非绝对阈值；同时展示实际的成本和 files_changed 数值，供用户自行判断。
3. 检查后再判断 files_changed 为零的会话是否可疑——规划、研究、仅评审等非编码会话可能确实产生费用，却没有差异。除了数值之外，还要说明会话的 session_name/项目大致是什么，而不只是将其标记为异常。

---

成本增长检测（成员）

1. 解析成员（与此技能中其他针对成员的视图采用相同方式）。
2. 选取两个长度相等、互不重叠且可比较的时间段。若用户未指定，默认对比“过去 30 天”和“再往前的 30 天”；除非用户明确要求更长时间，否则回溯时间最多为 3 个月。

   cawplan session user-trend --user-id <user_id> --from <period1_start> --to <period1_end>
   cawplan session user-trend --user-id <user_id> --from <period2_start> --to <period2_end>
   

3. 计算两个时间段之间的成本变化百分比。报告实际数值（例如“较上一时段增长 +340%，$42 → $185”），不要笼统地说“显著增长”——不要自行设定什么程度算“增长”的判断阈值；只需报告数值，由用户决定是否值得关注。如果上一时段的成本为 $0，则变化百分比未定义——应报告前后原始数值（“$0 → $X，本时段出现新活动”），不要计算百分比或除以零。

---

日期范围规则

• “last week” → --from <last Monday> --to <last Sunday>
• “this month” → --from <first of month> --to <today>
• “today” / “yesterday” → 使用 --date <YYYY-MM-DD>
• 如果未指定提示词，默认查询当前用户今天的报告。
• 如果提示词要求某项指标但未注明日期，除非措辞暗示更长的时间范围，否则默认使用今天。
• 使用 cawplan session dates 查找实际有数据的日期。

输出

请根据请求内容组织响应：

• 摘要：总费用（$）、总令牌数、该时段内的活跃成员数。
• 趋势：如果请求的天数超过 2 天，则提供每日费用表。
• 成员排名：费用排名前 5 的成员及其令牌数。
• 按模型/Agent 统计：按费用排序，并显示占总费用的百分比。
• 按产品/项目统计：列出会话数和费用。
• 提示词质量：如果已获取人工输入数据，则提供类别细分和质量评分分布。
• 关键观察：列出 1–3 个值得注意的模式（例如费用较高的日期、主要贡献者、异常的模型支出等）。

说明

• by-product 需要配置产品与仓库的映射（cawplan session product-repos）。
• product-* 命令需要产品的 unique_id，而不是名称。

参考资料

• references/CAWPLAN_OPEN_API.md