企业官网建设流程全解析

最近一段时间，我把 DeepSeek 的编程智能体当成了主力编码搭档，几乎所有模块开发都先跟它过一遍方案再动手。用得越深，越觉得不对劲：它不是不好用，而是太“听话”，以至于我有三件事完全被它惯坏了。第一，API 账户余额还剩多少，它从来不主动告诉我，经常是大型重构改到一半，啪一下账单归零；第二，一次会话里塞了五六个子任务，它还能勉强分清，但等我从它写的代码里回过神来，完全不知道哪块改到一半、哪块还没动；第三，它生成代码的速度比我读代码的速度快得多，我跟着它连续干三四个小时，脖子和脑子一起抗议。所以我决定，给它写三个插件，把这些“看不见、管不住、记不了”的东西，变成看得见、管得住、记得下的工具。

这三样东西分别叫：余额胶囊、任务面板、番茄钟。这篇文章就聊聊我为什么这么设计、具体怎么实现的，以及三个插件一起跑之后踩过的那些坑。如果你也在用类似支持事件钩子的编程智能体，这里面的选型思路和避坑经验应该可以直接抄。

1. 先说动机：三个日常场景暴露出的缺口

1.1 余额焦虑：一次“写一半没电”的崩溃现场

我到现在还记得那次。当时正在做接口层的重构，先让智能体把三个旧模块的依赖梳理清楚，再给出迁移方案。它干了大概二十分钟，回答到一半，直接冒出一行鉴权失败。我切到控制台一看，账户余额归零了。

那一刻最气的不是钱花完了，而是它没有任何一个环节提醒我“快没钱了”。API 账单是事后统计，余额在网页后台，代码生成过程里没有任何人会告诉你会话将断。对编码场景来说，这就是“写一半突然断电”。

后来我意识到，编程智能体的余额问题不是“查询”问题，而是“预警”问题。我不想在写代码的时候手动打开控制台，我需要的是一个能出现在对话上下文里的“油量表”。这个需求后来就成了余额胶囊。

1.2 任务失控：多文件改造时，上下文像一团乱麻

第二个场景发生在一次跨模块改造。我给它一句话：“抽出公共鉴权模块，改掉三个调用方，再补上单测。”它老老实实全干完了。

问题出现在 review 阶段：我根本分不清哪次改动对应哪个子目标。同一个文件里可能有三次改动，其中两处是“抽公共模块”做的，有一处是“改调用方”顺手做的。我在 diff 里来回跳，靠猜。

这事让我明白一个道理：智能体的上下文窗口再大，也只对模型自己有意义，人的工作记忆非常有限。人和 AI 协同做工程，必须有一个双方共享的外部事实源——谁在看、谁在改、哪个目标完成了、哪个目标还挂着。任务面板就是为这个做的。

1.3 时间失感：AI 写代码很快，人也跟着忘了休息

第三件事和效率有关，也和健康有关。DeepSeek 编程智能体的生成速度很快，快到什么程度？我这边还在读它上一个文件的注释，它已经开始改下一个文件了。连续三个小时，我基本没离开过座位。

我以前也用过番茄钟，但那是手动开、手动停，而且和代码会话完全脱节。我需要一个和智能体绑在一起的“节拍器”——到点了，不是弹个窗让我自己消停，而是它主动汇报进度，把要不要继续的选择权交给我。

这三个痛点本质上是同一件事：智能体闭着眼睛干活，人在外面干着急。解决思路也一致：把外部世界的状态（余额、任务、时间）注入到它的感知里，同时把它的行为提炼成人能跟上节奏的信号。

2. 插件机制选型：我最终选了事件钩子，而不是 CLI 和 HTTP 服务

2.1 三条可行路径的对比

给编程智能体做插件，路径其实没那么多。我先把当时能想到的三种方式摆在一起对比了一下：

我选了第三条。原因很直接：余额胶囊、任务面板、番茄钟三个插件的价值，都在于“在正确的时机提供正确的信息”，而时机是事件驱动的，不是用户手动驱动的。事件钩子是唯一能和“模型输出完成”“工具执行完成”这些时机对齐的方案。

2.2 事件钩子的协议设计

实际协议我做得很轻。每个插件是一个可执行文件，智能体通过配置文件声明要订阅哪些事件；事件以 JSON Lines 格式发到 stdin，一行一个 JSON；插件如果想注入信息，就在 stdout 写一条结果，同样是一行 JSON。

# ~/.config/deepseek-agent/plugins.yaml plugins: balance-pill: command: ~/.local/bin/balance_pill.py subscribe: [session_start, response_after] task-board: command: ~/.local/bin/task_board.py subscribe: [tool_execute, response_after] pomodoro: command: ~/.local/bin/pomodoro.py subscribe: [response_after, session_end]

三个插件共用同一个骨架，核心的 Python 骨架长这样：

import json import sys def emit(action: str, **data): # 向智能体输出一条结构化结果 sys.stdout.write(json.dumps({"action": action, **data}) + "\n") sys.stdout.flush() def main(): for line in sys.stdin: line = line.strip() if not line: continue event = json.loads(line) handler = HANDLERS.get(event.get("type")) if handler: handler(event) if __name__ == "__main__": main()

选 JSON Lines 而不是完整 JSON-RPC，最主要的原因是调试方便：直接用 jq 就能看事件流，出问题容易复现。但这个方案也有坑，后面会专门讲。

2.3 为什么事件钩子能解决“上下文注入”这个核心问题

三个插件真正要解决的问题是：把模型看不见的信息，变成模型上下文里的一部分。CLI 手动触发做不到主动，HTTP 服务又要自己处理鉴权和生命周期。事件钩子相当于给插件开了一扇门——智能体每完成一轮生成，插件都能决定要不要往上下文里塞一段话。

这段话会被模型当作背景信息读到，于是模型在生成下一段代码时，会“知道”余额快没了、任务清单在哪、番茄钟到点了。这不是在改智能体本身，而是在改它的感知环境。这个思路贯穿全部三个插件。

3. 余额胶囊：把事后账单变成模型自己会操心的油量表

3.1 余额信息从哪来

余额胶囊要管两样数据：账户余额快照，以及 token 消耗流水。

余额快照从账户接口拉取。编程智能体本身不会把余额放进上下文，所以插件每次在session_start事件里拉取一次，并做 5 分钟缓存，避免频繁调用触发限流。

token 消耗从每次响应的usage字段拿。这个字段通常包含prompt_tokens、completion_tokens、total_tokens。我按请求累积，就得到“本次会话已消耗”。

这里要提醒一点：不同版本、不同模型的usage字段结构不完全一样，有的还会在prompt_tokens_details里细分缓存命中情况。解析之前一定要先打日志，看一把真实响应长什么样，别对着文档硬写。

3.2 消费预测与“油量表”换算

余额数字本身不是最关键的，关键是“还能干多少活”。我用了最近 50 次请求的平均 token 消耗做 EMA 平滑，再乘上当前计价系数，得到“平均单次请求价格”。然后算：

def estimate_sessions(balance, avg_cost_per_request): if avg_cost_per_request <= 0: return None return int(balance / avg_cost_per_request)

这个“还能调用多少次”比纯余额数字更直观。比如余额是 12 块 3 毛 4，单次平均不到 1 分钱，那估算值就是一千多次。模型读到这个信息时，会主动调整工作策略：如果剩余次数看起来紧张，它会在回答里加一句“建议先跑测试，下一阶段重构可以延后”。

实测下来，这个“主动建议”出现的次数让我很意外。当我没给它余额信息时，它永远埋头干活；给了之后，它反而会像个有经验的同事一样提醒我收着点用。

3.3 缓释胶囊：何时注入，注入多少

“胶囊”这个名字来自缓释药片的隐喻——信息不能一次注入后就不管，也不能每次请求都刷屏。我的注入策略是：

• 首次（session_start）注入完整版：余额、会话消耗、预测次数、计价说明。
• 之后每隔 N 次请求（N=8）或余额变化超过 5%，注入精简版：只有当前余额和剩余次数。
• 当余额低于某个阈值（比如 2 块钱），把注入频率提高到每 3 次请求一次。

这个频率为什么还要调？因为上下文窗口是有限的，注入越频繁模型越“感知”得到，但也会占用 token、拉高成本。余额越低，风险越高，越值得占用 token。这是一个非常典型的“用 token 换安全”的取舍。

4. 任务面板：让一次会话升级成多任务工程现场

4.1 四态模型与字段设计

任务面板的数据模型我尽量做小：

from dataclasses import dataclass, field from typing import List @dataclass class Task: id: int title: str status: str # todo | in_progress | done | blocked files: List[str] = field(default_factory=list) dependencies: List[int] = field(default_factory=list) definition_of_done: str = ""

状态机只保留四个态：todo、in_progress、done、blocked。为什么不做更复杂的 in_review、waiting 之类？因为模型在生成时解析状态越简单越准确，人扫一眼也能看懂。复杂的流转关系用dependencies表达：一个任务如果依赖的任务未完成，它就不该被启动。

definition_of_done是最容易被忽略但最有用的字段：任务成立时，先让智能体写清楚“什么样子算完成”。比如“抽出公共鉴权模块并替换三个调用方，跑通 test_a/test_b”。没有这个字段，任务面板会退化成普通待办清单，起不到工程管理作用。

4.2 Markdown、SQLite、HTML 三层形态

数据的主存储我故意做成了 Markdown 文件，放在项目根目录.tasks/tasks.md。为什么不是 SQLite？因为 Markdown 是人眼可读、diff 友好、不需要额外依赖。每次任务状态变化，插件重写这个文件。

SQLite 是次形态：同样的事件流会同步写一份，用来做统计，比如每个任务平均耗时、每个任务关联的文件改动数。HTML 是衍生形态：把 Markdown 渲染成可以在编辑器里预览的面板视图。三者由同一份任务数据驱动，Markdown 是源，后两者是导出。

4.3 双向同步与“模型绕路”问题

面板不能只是给人看的，模型也得能更新它。我定义了三条命令：

• task list：列出当前任务
• task start #3：把任务 3 置为 in_progress
• task done #3：把任务 3 置为 done

模型在生成时可以调用这些工具，插件解析后更新数据。

最难处理的坑是“模型绕路”：智能体可能在任务面板完全没更新的情况下，直接动手改代码。毕竟它是生成式模型，不是严格遵守协议的执行器。所以插件不能只信模型主动设置的状态，还要做防御式校验——定期扫描工作目录里的文件修改时间，凡是有文件变化但没有任何任务处于 in_progress，就注入一条提醒：“检测到文件 xxx 变更，但当前没有进行中的任务，是否要将变更挂到某个任务？”

这个机制上线后，我至少三次被它提醒“挂错任务”或者“忘了建任务”，比靠自觉可靠多了。和模型协作时，外部事实的校验优先级一定要高于模型的自述。

4.4 和 git 工作流的配合

每个任务我会建议智能体用独立分支，比如task/3-extract-auth。任务 done 时，插件根据files字段生成 commit message 模板。这样 review 时可以按分支看 diff，和任务一一对应。

实测两个任务并行时，我基本不会再混淆“这个改动属于哪个目标”。这个插件把“对话里的一句提及”变成了“可勾选的外部事实”，模型不会因为上下文窗口滚动而遗忘，人也随时知道全局。

5. 番茄钟：不是简单计时，是在事件边界上等出来的节拍器

5.1 从“人记时”到“模型汇报”

番茄钟的核心不是“计时”，而是“到点时模型主动汇报、人做裁决”。所以这个插件维护的是一套状态机和规则，而不只是简单的定时器。

默认配置是：25 分钟工作，5 分钟短休；每 4 个番茄进入 15 分钟长休。参数全部写在配置里。我后来把工作长度调成过 40 分钟，也把短休调成过 3 分钟。不同任务类型确实需要不同节奏，比如“读代码做方案”适合长工作块，“改小 bug”适合短工作块。

5.2 在事件边界等待，而不是打断

这是全篇最想强调的一个坑。一开始我的方案是：计时器到点时，直接把强制提示注入到请求流。结果模型生成到一半，“时间到”这句话被它当成了要写的内容，直接作为注释塞进了代码里，污染了整个输出。

后来改成：番茄钟只在response_after事件边界检查。也就是说，模型完成一整轮生成之后，插件才有资格注入“到点汇报”。核心逻辑：

import time class PomodoroTimer: def __init__(self): self.state = "work" self.started = time.time() self.work_minutes = 25 self.cycles = 0 def handle_response_after(self): elapsed = time.time() - self.started if self.state == "work" and elapsed > self.work_minutes * 60: emit("inject_context", content=( "[番茄钟] 本轮工作块已到点。" "请停止当前工作，用两句话汇报进展，并等待用户决定继续/休息。" )) self.state = "awaiting_user"

这个awaiting_user状态很关键：插件不是直接把状态切到 break，而是等用户决定。用户说“继续”，工作块延长；用户说“休息”，状态才真正切到 break。这样既给了人主动权，模型也不会因为“被强制休息”而在生成上出现奇怪行为。

5.3 与任务面板的联动

番茄钟到点时，我会触发任务面板的进度刷新：当前 in_progress 的任务，如果过去一个番茄钟内没有任何文件变化，就注入一条“这个任务已经一个番茄钟没有文件变动，是否继续？”。这个联动把两个插件变成了一套机制——时间到了，任务的实时状态也跟着被审视。

我也踩过机械计时的坑：到点强制休息，哪怕我正专注排查问题。后来任务面板检测到文件系统有变化时，番茄钟会自动把当前工作块延长 10 分钟，避免在最高专注的时候被打断。这个设计来自一次惨痛经历：我正调一个断言，突然被模型注入“该休息了”，思路直接断掉。

5.4 实测效果：一个下午的节奏

装上番茄钟之后，一个典型工作日下午大概是：4 个工作块，每块 25 分钟，块与块之间模型会帮我总结“刚才完成了什么、下一步建议是什么”。我不再需要手动记录工作节奏，每天的产出和休息分布都变成可回看的数据。

比预想更好的部分是：番茄钟配合任务面板，会在每个工作块结束时自动暴露“该不该继续做这个任务”——如果任务在一个番茄钟里没有进展，模型会建议我换个任务切过去看，这比我自己凭感觉判断要客观得多。

6. 三个插件一起跑之后的复盘：协议、计数与信任问题

6.1 协议字段漂移：JSON Lines 的自由是要还的

三个插件各自独立演进时，问题来了：余额胶囊在某个版本给事件对象加了一个字段，而任务面板还在按旧字段解析。由于 JSON Lines 没有 schema 强制校验，这类错误只在特定事件组合下出现——可复现性极差，排查起来非常痛苦。

我的解决办法是在每个事件对象里加protocol_version，插件发现版本不匹配就直接打日志拒绝处理，而不是“默默解析错”。教训很清楚：即使是最简单的协议，第一版也必须带版本号。这个改动花了不到十分钟，但至少帮我省了一个晚上的调试时间。

6.2 usage 重复计数：流式响应的隐蔽陷阱

余额胶囊早期统计出来的会话消耗比真实值高出一倍，排查半天才发现是流式响应的坑：stream 模式下，部分 chunk 会携带 partial usage，最终响应也会携带累计 usage。如果我把所有响应里的 usage 都加起来，自然翻倍。

解决办法是：只处理finish_reason非空的那条响应。更稳妥的做法是，从usage里取completion_tokens做增量变化判断，没有变化就跳过。这也是为什么前面一直强调要把真实响应打日志看清楚——不同调用方式的解析策略完全不同。

6.3 信任边界：模型会绕过协议，所以要防御式校验

任务面板最容易被绕开。我用下来的体会是：智能体本质是“根据当前上下文生成最合理文本或代码”的系统，它遵守协议是概率性的，不是必然的。所以任何“让模型自己更新状态”的设计，都要配上“外部事实校验”。

具体做法就是前面提到的文件系统 diff 扫描、任务状态核对、自动提醒。这套防御式校验不仅管住了任务面板，也让余额胶囊更准——因为如果模型改文件不走面板，至少还有文件变更记录可以对照，避免任务和代码不一致。

6.4 一个意外收获：智能体开始“主动说话”了

装上三个插件之后，最明显的变化其实是“智能体会主动说话了”：余额低时会提醒省着用，任务乱时会建议先收拢范围，番茄钟到点时会汇报进展。这些都不是模型自己学会的，而是外部状态注入之后，它的上下文里终于有了“世界感”。

这个收获对我来说是最大的启发：AI 编程工具体验的上限，不只看生成速度有多快，还要看它对周围环境有没有感知。哪怕只是三个小巧的插件，只要让模型“看得到”余额、任务和时间，协作体验就会完全不一样。

这三个插件加起来不到一千行代码，没有用到任何复杂算法，但它们的实际价值，超过了我之前写过的很多“看起来更酷”的功能。如果你手头也有一个支持事件钩子的编程智能体，我建议别急着写炫酷的大插件，先把“余额看不见、任务管不住、时间摸不着”这三件小事解决掉，它们才是每天都在发生、最影响长期体验的痛点。

最后分享一个小习惯：我会把三个插件的日志都落到同一个目录，平时不怎么看，出问题时直接 tail 一把梭。保持协议简单、日志完整、状态可校验——这三点几乎可以延伸到所有给 AI 工具做扩展的场景里。