造了个写周报的工具 agent

经常上班的人都知道🤣，写日报/周报/月报这事每个公司要求都不一样。有的要分三大块写，有的要填表格，有的得按项目一条条列，也有可以自由发挥的。

不是写周报本身多烦，是烦重复和整合工作内容。最早我用过一个脚本，从 git log 拉出提交记录再手写成周报，但每次都得调整格式，比写周报还花时间。

实在没忍住——干脆自己写个工具，让大模型来干这活。格式不对就调调模板，一劳永逸。于是就有了 commit-log-daily。

这篇文章不聊安装配置，那个 README 里都有。就说说这个工具几个核心设计是怎么来的——每一条都是被真实需求逼出来的。

模板——把格式交给用户

最早遇到的问题：市面上有很多工具能从 git 拉日志，但格式都是写死的，或者是固定几套模板。不符合公司的格式？那你就还得手动改一遍。有人可能觉得，格式这事找个通用模板不就行了？但待过几家不同公司就明白——通用模板就是个伪命题。有的公司要按项目维度汇报，有的要按”需求/缺陷/优化”分类，有的还带工时统计。每个团队要求都不一样，不可能一个模板通吃。

所以我做了个可配置的模板系统，用户自己说了算。

实现上不复杂——用一个  分隔线把模板文件切成两段。举个例子，假设公司要求周报写成这样：

一、本周工作内容
  · 项目A — 完成了登录页重构，修复了两个线下bug
  · 项目B — 完成了数据库索引优化，查询性能提升了40%
二、存在问题与风险
  · 项目A 依赖第三方SDK升级，排期待确认
三、下周计划
  · 项目A 联调测试
  · 项目C 技术方案评审

那模板就可以写成：

<!-- DATA 以上：告诉 LLM 怎么写 -->
分成三大块：本周工作内容、存在问题与风险、下周计划。
本周工作内容按项目归类，每个项目先写功能变更再写bug修复。
用业务语言，别说技术细节。

<!-- DATA -->

<!-- DATA 以下：骨架参考 -->

## 一、本周工作内容
  · 项目A — 完成了登录页重构，修复了两个线下bug
  · 项目B — 完成了数据库索引优化，查询性能提升了40%

## 二、存在问题与风险
<!-- LLM 根据 git 情况和用户补充填写 -->

## 三、下周计划
<!-- LLM 根据上下文推断 -->

指令段告诉 LLM”怎么写”——语气、侧重点、分类逻辑。这段内容在生成报告时拼到 LLM 的 system prompt 里。骨架段告诉 LLM”你平时提交的汇报长什么样。

有同事问过：为什么不用 Handlebars 把模板真正解析掉？我是这么想的——内容生成是 LLM 做的，模板只是参考。如果用引擎把结构定死了，遇到”这个项目本周只有修 bug 没有新功能，排版上怎么调整”这种灵活判断，模板引擎处理不了，但 LLM 做起来很自然。

模板写好后在项目里敲 /templates 就能管理，新建、编辑、设为默认都在界面里完成。

两个阶段——先翻代码，再写报告

后来改成拆成两步走。

第一步，收集数据。

LLM 只能用数据工具：扫描 git 提交记录、检查未推送的代码、列出项目列表。所有仓库翻完后汇总给你看：

这周 scan 了 3 个项目，共 24 次提交。
有 2 次提交信息比较简略，你看是不是补充一下？
还有 1 个仓库有未推送的提交。
工作相关的其他仓库有没有要加进来的？

这时候你可以补充隐性工作——帮同事排查了个线上问题、开了两场需求评审会。这些 git 提交里没有，但周报里得有。这一步的关键是：先让人确认数据全不全，再往下走。

第二步，生成报告。

数据确认完了，LLM 切换到报告模式。这时候它能用生成和保存的工具。。

两个阶段之间靠一个 [PHASE:generate] 标记切换。——收集阶段给的是翻代码的工具和数据校验的指令，生成阶段给的是写报告的模板和保存文件的能力。换阶段就是切到另一套配置。

实际用下来有个好处：LLM 在收集阶段会认真检查数据，因为它知道自己不用急着写报告。翻日志的时候如果发现提交信息不清晰，会主动跟用户确认。数据收集阶段的时间拉长一点没关系，关键是把事情弄清楚。

分支和提交——引导比强制好

Git 提交记录是周报的原材料，但这个材料质量嘛……有人写”update”，有人写”fix”，还有人写”111”。这些拿给 LLM 也写不出什么来。

一开始想过加个提交规范校验，不符合直接报错。但很快否了——强制规范就是给人添堵，而且每个团队的规范也不一样。不如让 LLM 来做这件事，用引导代替强制。

实际做法很简单：LLM 翻完提交后扫一眼质量，发现提交信息太敷衍就问你一句：

“这几个提交信息比较简略，你看是不是补充一下具体做了什么？”

分支命名也是一样。feat/login-page、fix/header-bug、refactor/db-layer 能自动归类到对应板块。develop、temp、my-branch 这种看不出来路的，它会问你这部分改了什么。

不强制，不报错。就是问一句。多数人这时候会想起来补上：”哦对，这个是改登录页面的”。报告就这么完整了。

有意思的是，用了一段时间后发现一个意外的效果——大家慢慢养成了写清楚提交信息的习惯。 原因不是因为有规范，而是因为没写清楚就会被追问，问多了自己也嫌烦，索性提交的时候写明白。这个效果比加规范校验好得多。规范校验是”你不这么写我就不让你提交”，而引导是”你不写清楚我就多问两句”——后者给人的感受完全不一样。

安全方面

Agent 能执行命令，自然要考虑安全问题。做法挺常规的：

只允许几个 git 子命令：log、branch、diff、show、status。别的命令不给用。这也是为什么很多自动化功能做在工具里而不是通过 shell 命令执行——宁可多写几行代码封装，也不给 LLM 开一个”随便执行”的口子。
执行命令时用 execTool，参数传数组。这样就算有人传了奇怪的参数，也不会被 shell 解释执行。这个设计实际上是在给”给 LLM 开命令权限”这件事加底线——LLM 也会犯错，底层的安全不能靠 LLM 自觉。
execTool 这个 tool call 内部设计了一层防护，判断执行命令的安全等级 危险/有副作用/安全 , 其中危险 的命令不会执行，有副作用的命令会提示用户先确认，判断等级有单独的llm判断+本地判断兜底。
默认开着安全模式，想放开权限得自己手动关。

一些总结

这个项目从最开始一个调 API 的脚本，慢慢长成现在这样。前后大改了好几次，每次都是因为”这样用着不舒服”才改的。

几个核心设计回过头来看，都是围绕同一个目标转的：

模板可配置，是为了让报告格式可控——不管公司格式怎么变，改模板就行，不碰代码。
两阶段分离，是为了让数据收集不遗漏——数据全了，报告才靠谱。
提交流程引导，是为了原始材料有保障——输入好了，输出才能好。

代码在 GitHub 上：commit-log-daily。

一些还没做好的地方

文章写到这里都是做得还行的地方，也说几个不太满意的。

阶段切换依赖 LLM 在回答末尾输出 [PHASE:generate] 标记。大多数时候它能做对，但偶尔会忘记写这个标记，或者写成带空格的格式。虽然代码里做了兼容处理，但一旦切换失败，LLM 会继续用收集阶段的工具集，而那时候数据其实已经够了——就是卡在”该写报告了”这一步，有点尴尬。

还有一个比较遗憾的——没找到企业微信自动提交周报的接口。国内很多公司用企业微信的”汇报”功能来收周报，如果能直接提交进去，那就真正全自动了。但翻了一圈，企业微信没有公开的提交接口，这个是外部限制，自己使不上劲。

只有窗口记忆，没有长期记忆。不会记住一些用户习惯以及项目的一些信息，比如”这个项目是做什么的”。

另一个想做但没时间动的是多 Agent 支持——现在是一个 Agent 干所有活，如果拆成”数据收集 Agent””质量检查 Agent””报告生成 Agent”，每个专注于一件事，应该能做得更细。比如专门的数据收集 Agent 可以同时扫描多个仓库，不用一个个来。

不过这也可能是想多了。目前这样够用，先凑合着。