从意图到代码：如何用自动化思维与工程实践克服项目启动障碍

1. 项目概述：一个记录意图却无法写代码的构建日志

如果你在区块链或者AI领域折腾过一阵子，大概率会和我有同感：最难的从来不是技术本身，而是把脑子里那个清晰无比的“意图”，变成硬盘里第一行可执行的代码。我管这个叫“意图到实现的鸿沟”。最近，我的一个“AI合规栈”项目就卡在了这个鸿沟边上，整整六个星期，构建日志里反复记录着同一个意图，但那个关键的Python文件就是没被创建出来。这个项目本身并不复杂，核心是监控欧洲证券和市场管理局（ESMA）关于加密资产市场法规（MiCA）的技术标准动态，自动解析、对比，并通过Telegram推送结构化警报。工具链是现成的，架构图在脑子里画了无数遍，甚至第一个函数fetch_esma_feed()的伪代码都在Markdown文档里躺了好几个版本。但就是这“打开终端，创建文件，写下函数签名”的第一步，像是有无形的阻力。相比之下，我那些在Arbitrum、Base、Linea上自动运行的ETH网格交易机器人，却能在无人干预的情况下，每五分钟稳定执行一次。这其中的反差，促使我深入思考自动化、决策与执行惯性之间的关系。这篇记录，就是关于这个“卡住”的状态，以及我如何尝试用“构建公开”的方式，给自己设置一个无法回避的deadline，来跨越这最初的障碍。

2. 核心思路解析：自动化如何绕过决策，而非克服惯性

2.1 网格机器人的“无感”运行机制

我的ETH网格机器人之所以能“无感”运行，其核心设计哲学在于“移除运行时决策点”。这不是什么高深的AI，而是一种极简的系统设计。

1. 配置即代码，一次决策，长期生效：机器人的所有参数——交易对、价格区间、网格数量、投入金额——都在一个配置文件中定义。这个文件本身就是“第一行代码”的产物。一旦完成并验证，它就被提交到代码仓库，成为真理之源。
2. 基于时间的触发器（Cron）：执行引擎不判断“现在是不是好时机”，它只忠实于时间表。一个每5分钟运行一次的Cron任务，会无条件地拉起主程序。
3. 无状态与幂等性设计：每次执行，机器人都会从链上或交易所API读取最新状态（如持仓、市场价格），然后根据配置文件中固化的逻辑进行计算，决定是否挂单、撤单或调整。这个过程不依赖上一次执行的内存状态。即使程序崩溃重启，只要配置没变，它就能从当前市场状态重新开始，结果是一致的。
4. 权限与密钥的托管：执行环境的私钥或API密钥已被安全地配置好。机器人运行时，不需要“我”来授权每一笔交易。决策权在配置阶段就已经让渡给了程序逻辑。

注意：这里的“无权限”并非指不需要任何权限，而是指在运行时不需要人工进行交互式授权。所有必要的权限凭证已在部署阶段以安全的方式（如环境变量、硬件安全模块）预先配置完毕。这是自动化能成立的前提，但也是安全风险的关键点，必须通过严格的访问控制和安全实践来管理。

这套机制的成功，关键在于它将“做什么”（决策）和“何时做”（触发）彻底分离，并将“做什么”固化在代码中。自动化并没有克服我作为人类的惰性或决策疲劳，它聪明地绕开了这些环节。在机器人运行的生命周期里，已经不存在“我需要决定现在是否运行它”这个时刻了。

2.2 AI合规栈的“决策阻塞”困境

反观这个AI合规栈项目，它恰恰在起点上就布满了需要人工介入的决策点，从而放大了“启动惯性”。

1. 技术栈选择焦虑：虽然知道用feedparser解析RSS，用difflib做文本对比，用requests和python-telegram-bot发通知，但总会想“有没有更好的库？”“是不是该用异步框架？”“这个架构未来好扩展吗？”这些本应在快速原型阶段搁置的问题，变成了启动的绊脚石。
2. 项目初始化的“仪式感”：创建一个新仓库，是叫ai-compliance-monitor还是mica-esma-watcher？要不要初始化poetry或pipenv？.gitignore模板用哪个？这些微不足道的选择消耗了本就不多的启动能量。
3. “完美主义”幽灵：第一个函数fetch_esma_feed()，我总想着一口气写出完美的错误处理、重试逻辑、日志记录和单元测试。结果就是，连一个仅仅返回feedparser.parse(url)的简单函数都无法落地。意图被困在了“要写就写好”的执念里。
4. 缺乏即时的外部压力：网格机器人在真金白银地运行，宕机意味着潜在亏损，这是一种强烈的外部驱动。而合规监控工具，其价值是预防性的、信息性的，它的“宕机”——即我的不行动——在短期内没有直接、可见的后果。ESMA的咨询文件依然会在官网发布，只是从“自动推送”变成了“我手动去浏览器打开标签页查看”。这种后果的延迟性和弱反馈性，进一步削弱了启动的动力。

问题的本质在于，这个项目的自动化流程始于一个需要人工完成的创造性编码动作，而网格机器人的自动化流程始于一个无需决策的定时任务。前者要求跨越从0到1的创造性鸿沟，后者只需要维护从1到100的重复性运行。

2.3 “构建公开”作为外部强制力

这就是为什么我选择“构建公开”。我把这个半成品的构思、卡住的状态、甚至自我检讨，都写进一个公开的构建日志。这个日志由一个运行在老旧迷你主机上的简单Agent自动提交到代码仓库。

• 它创造了 accountability：当意图被加上时间戳并公开，它就从一个私人的念头，变成了一个对外的、微小的承诺。你无法悄悄地、毫无痕迹地一再拖延。下周一日志自动更新时，它要么记录进展，要么成为第七次失败的明证。这种社会性压力（哪怕观众很少）是一种强大的心理工具。
• 它使“无形”变得“可见”：浏览器里打开的十几个ESMA网页标签是混乱的、私人的、易忘的。而日志中“未实现”的条目是结构化的、公开的、持久的。这种对比本身就在凸显工具本该提供的价值：将信息混沌转化为结构化警报。
• 它降低了启动的心理成本：当“完成一个完美的工具”这个宏大目标让人望而却步时，日志允许我将目标极端地缩小、具体化。就像我给自己设定的“W15周五目标”：不写逻辑，只写一个空函数和一句文档字符串。这听起来几乎可笑，但它切中了要害——打破“无代码”的状态。

3. 从意图到第一行代码：实操拆解与心理突破

3.1 定义“最小可交付成果”

对抗启动瘫痪最有效的方法，就是重新定义“完成”。对于这个合规监控工具，我将其终极目标拆解为多个“最小可交付成果”，并为第一个MVP设定了荒谬般的简单标准：

MVP 0.1 目标（W15周五晚）：

• 创建仓库：ai-compliance-stack
• 添加一个文件：esma_fetcher.py
• 实现一个函数：fetch_esma_feed(url: str) -> dict
• 函数内容：只需函数签名、"""Fetch and parse ESMA RSS feed."""这样的文档字符串，以及一行return {}或pass。
• 编写一个测试：test_fetch_esma_feed.py，里面只测试这个函数能被导入和调用，甚至不用验证返回值。
• 提交信息：feat: initial commit with stubbed ESMA fetcher

这个列表的关键在于，它完全避开了所有“困难”和“复杂”的部分。没有网络请求，没有HTML解析，没有差异对比，没有消息推送。它只解决一个问题：让项目从“仅存在于文档和想象中”变为“在版本控制系统里有一个名字和结构”。

3.2 执行过程：对抗“下一步做什么”的迷茫

即使目标如此简单，执行时依然会有阻力。下面是我记录的具体操作流，以及每个步骤背后对抗心理阻力的思路：

1. 打开终端：这本身就是第一个动作。我把它和“泡杯咖啡”这个无脑动作绑定。咖啡机启动时，终端必须已经打开。
2. cd ~/projects：进入项目目录。保持一个固定的、整洁的工作区目录，减少寻找路径的决策。
3. mkdir ai-compliance-stack && cd $_：创建项目文件夹并立即进入。$_代表上一个命令的最后一个参数，是个实用小技巧，避免重复输入或上下键查找。
4. git init：初始化仓库。这一步没有任何成本，但它在心理上标志着“项目开始了”。
5. echo “# AI Compliance Stack\n\nMonitoring ESMA MiCA technical standards.” > README.md：快速创建README。内容简陋没关系，它是一个占位符，定义了项目的核心目的，防止后续偏离。
6. 创建.gitignore：我准备了一个通用的Python.gitignore模板文件，直接复制过来：cp ~/templates/gitignore-python .gitignore。不要现场去想该忽略什么，用模板。
7. 创建核心文件：

   touch esma_fetcher.py touch test_esma_fetcher.py

   touch命令创建空文件。空文件是可怕的，但也是必须跨越的坎。
8. 编写“空洞”的代码：esma_fetcher.py：

   """ ESMA Feed Fetcher Module. Core functionality for monitoring ESMA regulatory publications. """ def fetch_esma_feed(feed_url: str) -> dict: """ Fetches and parses the ESMA RSS/Atom feed. Args: feed_url (str): The URL of the ESMA regulatory feed. Returns: dict: A dictionary representing the parsed feed content. Structure to be defined in later implementation. """ # TODO: Implement actual feed fetching and parsing logic. # This will involve requests/httpx, feedparser, and error handling. return {}

   看，它什么也没做。但它存在了。它有类型提示，有文档字符串，有一个明确的TODO注释指向未来。这比Markdown里的代码块前进了一光年。
9. 编写“可笑”的测试：test_esma_fetcher.py：

   """ Tests for the ESMA feed fetcher. """ from esma_fetcher import fetch_esma_feed def test_fetch_esma_feed_exists(): """ Simply tests that the function can be imported and called. This is a placeholder to establish the testing pattern. """ # Use a dummy URL for now dummy_url = "https://www.esma.europa.eu/rss" result = fetch_esma_feed(dummy_url) # For now, we only assert that it returns something (even an empty dict). assert result is not None print("✓ Basic import and call test passed.")

   这个测试几乎毫无意义，但它完成了两件事：① 验证了模块导入路径正确；② 建立了测试文件的结构和命名规范。
10. 初始提交：

    git add . git commit -m “feat: initial commit with stubbed ESMA fetcher”

    提交信息遵循约定式提交规范，即使内容简单，也培养好习惯。
11. 推送到远程仓库：

    # 先在GitHub/GitLab上创建空仓库，然后关联 git remote add origin <your-remote-repo-url> git branch -M main git push -u origin main

    推送是“构建公开”的关键一步。代码现在不属于你一个人了，它存在于公共领域。

完成以上所有步骤，可能只用了15分钟。但这15分钟，将项目从一个“想法”推进到了“有据可查的工程实体”状态。最大的心理障碍被清除了。

3.3 实操心得：降低启动摩擦的工程技巧

• 准备模板和脚本：将常用的项目结构、.gitignore、setup.py/pyproject.toml基础内容、甚至CI/CD配置文件做成模板。项目初始化从“创造”变为“复制并微调”，能节省大量决策精力。
• “仪式化”启动流程：为自己设计一个固定的项目启动清单（Checklist）。每次新项目都严格按清单操作，形成肌肉记忆，避免在“下一步做什么”上耗费脑力。
• 立即建立反馈循环：即使只是一个空函数，也立即配上测试并运行pytest。看到“1 passed”的绿色输出，能提供最即时的正反馈，对抗挫败感。
• “糟糕的初稿”哲学：接受第一版代码是糟糕的。它的唯一使命就是存在。优化、重构、完善是后续迭代的工作。写下一个return None的函数，远比在脑海中构思一个完美的函数更有价值。

4. 工具链与架构设计思路

虽然MVP 0.1简单到可笑，但完整的工具链和架构早在规划之中。明确最终形态有助于理解每一步前进的方向，避免在后期做颠覆性改动。

4.1 核心工具链选型与理由

4.2 系统架构设计草图

整个系统可以设计为一个轻量级的、模块化的守护进程。

+-------------------+ +----------------------+ +-------------------+ | Scheduler | | Core Fetcher | | Diff Engine | | (APScheduler) |----->| (esma_fetcher) |----->| (difflib) | | 定时触发任务 | | 抓取&解析ESMA源 | | 对比新旧内容 | +-------------------+ +----------------------+ +-------------------+ | v +-------------------+ +----------------------+ +-------------------+ | Alert Dispatcher| <----| Result Processor | <----| Change Detector | | (Telegram Bot) | | (判断是否需告警) | | (判断是否有变) | | 推送结构化消息 | +----------------------+ +-------------------+ +-------------------+ | | (存储历史) v +-------------------+ | Local Storage | | (SQLite DB) | +-------------------+

数据流说明：

1. 调度器：每天在指定时间（如欧洲工作日上午9点）触发一次抓取任务。
2. 抓取与解析模块：访问ESMA的RSS源URL，使用feedparser解析，将结构化数据（标题、链接、发布时间、摘要）传递给下游。
3. 变更检测器：将本次抓取的内容与SQLite中存储的上一次内容进行对比。对比可以是全文哈希，也可以是关键字段（如标题+发布日期）的组合比对。
4. 结果处理器：如果检测到变更（新文件发布、旧文件更新），则生成一个变更摘要，并触发告警。
5. 告警分发器：将变更摘要格式化为易读的消息（Markdown格式），通过配置好的Telegram Bot发送到指定群组或频道。
6. 本地存储：无论是否有变更，都将本次抓取的内容快照存入SQLite，作为下一次对比的基准。

这个架构清晰地将关注点分离，每个模块职责单一，便于独立开发、测试和替换。

4.3 从Stub到MVP 1.0的演进路径

有了0.1版本的空壳，下一步就是沿着架构图，以增量的方式填充血肉：

1. 迭代 0.2：让fetch_esma_feed真正工作

   • 目标：函数能实际请求网络并返回解析后的数据字典。
   • 实现：
     • 在函数内使用httpx.get()获取Feed原始XML。
     • 使用feedparser.parse()解析响应内容。
     • 添加基本的超时和异常处理（try...except）。
     • 返回feedparser解析后的标准字典结构。
   • 测试更新：编写测试，使用一个已知的、稳定的公开RSS源（如某个博客）进行集成测试，验证返回的数据结构包含预期的键（如feed.title,entries）。

2. 迭代 0.3：建立数据持久层

   • 目标：能够将抓取到的条目存储到SQLite数据库。
   • 实现：
     • 设计简单的表结构：id,guid,title,link,published,content_snippet,fetch_time。
     • 使用sqlite3标准库或sqlalchemy创建连接和CRUD操作。
     • 创建save_feed_entries(entries)和get_latest_entries(limit=N)函数。
   • 注意：guid或link应作为唯一标识，避免重复存储。

3. 迭代 0.4：实现差异对比逻辑

   • 目标：比较本次抓取和上次存储的条目，识别出新条目。
   • 实现：
     • 从数据库获取最近一次抓取的所有条目ID/链接集合。
     • 将本次抓取的条目ID/链接集合与旧集合对比，找出差集（新条目）。
     • 对于更新（相同链接但内容可能变），可以对比title或content_snippet的哈希值。
     • 返回一个“变更列表”。

4. 迭代 0.5：集成Telegram告警

   • 目标：当检测到变更时，向Telegram发送一条通知。
   • 实现：
     • 申请一个Telegram Bot Token。
     • 使用python-telegram-bot库，实现一个简单的消息发送函数send_telegram_alert(changes: list)。
     • 将变更列表格式化为清晰的Markdown消息，包含标题、链接和发布日期。
   • 安全提示：Bot Token必须通过环境变量或Pydantic Settings读取，绝不能硬编码在源码中。

5. 迭代 0.6：引入调度器

   • 目标：让整个流程自动定时运行。
   • 实现：
     • 使用APScheduler创建一个BlockingScheduler。
     • 将前面的抓取、对比、存储、告警逻辑封装成一个主函数run_monitoring_job()。
     • 配置调度器每天在指定时间运行run_monitoring_job。
     • 将脚本打包为一个长期运行的守护进程（或用systemd/supervisor托管）。

6. 迭代 1.0：完善与部署

   • 目标：达到生产可用状态。
   • 工作：
     • 增强错误处理与重试机制。
     • 添加更详细的日志记录。
     • 编写完整的单元测试和集成测试套件。
     • 使用Docker容器化，方便部署。
     • 编写清晰的部署和配置文档。

通过这样一步步的迭代，每个阶段都有明确、可达成的目标，最终就能在不知不觉中完成一个看似复杂的系统。

5. 常见问题与避坑指南

在从零构建这类自动化工具的过程中，我踩过不少坑，也总结出一些共性的问题和解决方案。

5.1 网络请求与反爬虫策略

问题：直接、频繁地请求官方机构网站，可能遭遇IP限制、请求失败或得到非预期内容（如验证页面）。

解决方案与技巧：

• 设置合理的请求头：模仿真实浏览器的User-Agent。使用httpx时可以这样设置：

  headers = { 'User-Agent': 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.124 Safari/537.36' } client = httpx.Client(headers=headers, timeout=30.0)

• 使用会话与连接池：httpx.Client()或requests.Session()可以复用TCP连接，提升效率并保持一些会话状态。
• 实现指数退避重试：对于临时性网络错误，重试是必须的。可以使用tenacity库优雅地实现。

  from tenacity import retry, stop_after_attempt, wait_exponential @retry(stop=stop_after_attempt(3), wait=wait_exponential(multiplier=1, min=4, max=10)) def fetch_feed_with_retry(url): response = client.get(url) response.raise_for_status() # 触发重试的另一个条件 return response.content

• 尊重robots.txt：检查目标网站的robots.txt，确保你的抓取行为是被允许的，并遵守Crawl-delay指令。对于ESMA这类公共信息网站，通常比较友好，但仍需保持礼貌的抓取频率（如每天一次）。

5.2 数据解析与格式稳定性

问题：网站Feed的格式可能发生变化，导致解析失败或数据提取错误。

解决方案与技巧：

• 防御性解析：不要假设Feed结构永远不变。使用.get()方法安全地访问字典键，并提供默认值。

  feed_title = parsed_feed.feed.get('title', 'No Title') for entry in parsed_feed.entries: link = entry.get('link', '') # 进一步清洗和验证link

• 数据验证与清洗：使用pydantic模型对解析后的数据进行验证和标准化，确保后续流程处理的是结构良好、类型正确的数据。

  from pydantic import BaseModel, HttpUrl from datetime import datetime class FeedEntry(BaseModel): guid: str title: str link: HttpUrl # 自动验证URL格式 published: datetime | None = None summary: str = ""

• 监控与告警：在解析逻辑外层添加监控。如果连续多次解析失败，或解析出的条目数异常（例如为0），应触发一个更高级别的运维告警（如发送邮件或另一个紧急Telegram通知），提示“解析器可能已失效”。

5.3 状态管理与幂等性

问题：脚本崩溃后重启，如何避免重复处理条目或漏处理条目？

解决方案与技巧：

• 使用数据库记录状态：这是最可靠的方式。每次成功处理一个条目后，就在数据库中标记录入时间、处理状态和唯一标识（guid或link）。下次运行时，先查询已处理的标识集合。
• 实现“至少一次”语义：确保你的处理逻辑是幂等的。即，即使同一个条目被处理多次，结果也应该是一样的（例如，向Telegram发送一模一样的消息两次，虽然不完美，但比漏发好）。对于发送消息，可以在消息内容中包含一个基于条目内容和日期的唯一ID，由接收端做去重判断（如果可行）。
• 使用事务：在保存处理结果和更新状态时，使用数据库事务，确保原子性，避免状态不一致。

5.4 配置与密钥安全管理

问题：Telegram Bot Token、数据库路径等敏感或环境相关的配置如何管理？

解决方案与技巧：

• 绝对禁止硬编码：任何密钥、Token、密码都不能出现在源代码中。
• 使用环境变量：这是十二要素应用推荐的方法。在生产环境中通过Docker、Kubernetes或系统服务文件注入。
• 结合.env文件用于开发：使用python-dotenv库在开发时从.env文件加载环境变量。务必将.env添加到.gitignore，并提供一个.env.example文件说明需要的变量。
• 使用Pydantic Settings进行强类型管理：这是我强烈推荐的方式。它能集中管理所有配置，提供类型验证和默认值，并支持多种来源（环境变量、.env文件）。

  from pydantic_settings import BaseSettings class Settings(BaseSettings): telegram_bot_token: str esma_feed_url: str = "https://www.esma.europa.eu/rss" db_path: str = "./compliance_data.db" class Config: env_file = ".env" settings = Settings() # 使用时：settings.telegram_bot_token

5.5 部署与长期运行

问题：脚本如何在服务器上稳定、可靠地长期运行，并在崩溃后自动重启？

解决方案与技巧：

• 不要依赖终端和SSH会话：在终端中直接运行python main.py，一旦SSH断开，进程就结束了。
• 使用进程管理工具：
  • Systemd（Linux）：创建一份.service文件，可以定义依赖、重启策略、日志输出等。这是生产环境的标准做法。

    [Unit] Description=AI Compliance Monitor After=network.target [Service] Type=simple User=monitor-user WorkingDirectory=/opt/ai-compliance-stack Environment="PATH=/opt/ai-compliance-stack/.venv/bin" ExecStart=/opt/ai-compliance-stack/.venv/bin/python -m src.main Restart=on-failure RestartSec=10s [Install] WantedBy=multi-user.target

  • Supervisor：一个纯Python的进程管理工具，配置简单，同样支持自动重启。
• 容器化部署：使用Docker将应用及其所有依赖打包成一个镜像。这保证了环境一致性，并且可以方便地在任何支持Docker的机器上运行。

  FROM python:3.11-slim WORKDIR /app COPY pyproject.toml poetry.lock ./ RUN pip install poetry && poetry config virtualenvs.create false && poetry install --no-root COPY . . CMD ["python", "-m", "src.main"]

• 日志是关键：确保应用将日志输出到标准输出（stdout）和标准错误（stderr），这样进程管理工具（如systemd journal或Docker）才能捕获到。使用Python的logging模块进行结构化日志记录，便于排查问题。

跨越从意图到第一行代码的鸿沟，其核心不在于技术能力，而在于对抗初始惯性、管理心理阻力的策略。通过“构建公开”制造外部压力，通过定义“最小可交付成果”降低启动门槛，通过清晰的架构图和迭代路径消除对未知的恐惧，再辅以扎实的工程实践来应对具体的技术挑战，一个想法最终才能落地为真正运转的工具。我的ETH网格机器人之所以能无声运行，是因为我在过去已经为它完成了所有这些“第一次”的决策。而现在，对于AI合规栈，随着fetch_esma_feed这个空洞但存在的函数被提交，最艰难的一步已经迈出。剩下的，不过是沿着既定的路径，用一次次的微小提交，将意图逐步填充为完整的现实。日志的下一个条目，终于可以记录一些不同的东西了。