用 Agent 开发影刀：从知识库、元素探索到代码同步
介绍我为什么整理影刀开发知识库，以及如何让 Agent 查 API、探索网页元素、编写真实影刀项目代码，并通过同步工具交回影刀编辑器验证。
给 Agent 一套能查、能写、能同步的影刀开发环境
知识库负责提供 API、限制和排错依据；Agent 在真实项目目录写代码；浏览器插件帮助探索页面；同步工具负责把外部修改登记并编译。
查看影刀开发知识库 →API · 示例 · 排错
查依据 · 写代码
DOM · 元素 · 流程
登记 · 编译 · 验证
为什么要做这个知识库
影刀的可视化指令已经比较容易上手，但我实际做编码版开发时，最直接的感受是：官方 API 说明偏少，有些说明也不够清楚。有些能力只看到方法名，不容易确认参数怎么传；有些市场指令在界面里能用，切到代码后却不知道真实入口；遇到异常时，也很难从一条报错快速定位到正确用法。
我最初整理知识库，是为了让自己查得更快。后来发现，同一份资料也可以直接成为 Agent 的影刀开发上下文。
- 参数和返回值不够清楚
- 市场指令缺少编码版说明
- 踩过的坑下次还要重新查
按浏览器、Excel、日志、市场指令等主题查文档和例子。
让 Agent 先查依据，再回答问题或修改真实项目代码。
它不是影刀官方文档的镜像，也不是把所有源码塞进仓库。当前更像一层“开发者翻译”：
- 把常用 API 整理成适用场景、参数、最小示例和注意事项；
- 把市场指令的调用方式和参数映射单独记录；
- 把踩坑结论、待验证事项和错误修正留下来；
- 给 Agent 写清楚边界，例如不猜 API、不把知识库当业务项目、不把编译成功说成业务验证成功。
让 Agent 帮我回答影刀问题
最简单的用法，不是立刻让 Agent 改代码，而是先把知识库接进它能访问的目录。
不同 Agent 的配置方式不完全一样，但目标相同：让它可以读取 xbot-AI-docs，并知道影刀问题要优先查询这里。Codex、Claude Code 可以在项目规则里写明知识库位置；OpenClaw 这类长期运行的 Agent，可以把知识库目录配置为只读资料源。
影刀里怎么批量写入二维表格？不要猜 API，查知识库后给我最小示例和依据路径。
current project → docs/excel.md → examples/同时说明依据文件、适用边界，以及哪些行为仍需在真实影刀环境运行验证。
我通常会在问题里加三个要求：
- 先查当前项目，再查知识库。 当前项目已有写法往往比通用文档更贴近真实业务。
- 给出依据路径。 这样可以快速判断 Agent 是查到的，还是凭普通 Python 经验推断的。
- 不确定就标注“需运行验证”。 尤其是市场指令参数、页面元素和编辑器行为，不能把静态阅读当成真实运行。
知识库地址：apexcheng/xbot-AI-docs
让 Agent 直接写影刀项目代码
知识问答只是第一层。更实用的方式，是让 Agent 直接进入真实影刀项目目录开发。
这里最容易犯的错误，是把知识库目录当成项目目录。知识库存的是规则和资料，真正要改的 main.py、package.json 和业务文件仍然在影刀创建出来的应用目录里。
从新建影刀应用到完成代码同步
创建真实应用并确认它的项目目录；Agent 后续必须在这个目录工作，而不是在知识库里写业务代码。
从知识库复制通用规则；使用 Claude Code 或 Codex 时，再按需复制对应入口和只读子 Agent 配置。
说明业务目标、输入输出、页面和人工确认点；小改直接做，大任务再建立 TASK.md 维护阶段状态。
在授权的浏览器页面中检查 DOM、测试元素定位并梳理操作路径，再把验证过的选择器写进项目。
登记代码流程、编译入口和辅助模块；最后仍要在影刀编辑器里运行，确认页面、参数和业务结果。
第一步：复制项目规则
知识库根目录的 AGENTS.md 是通用规则入口，也可以复制到真实影刀项目根目录。它会提醒 Agent：
- 优先读取现有代码，不凭经验猜影刀 API；
- 浏览器业务优先使用
xbot.web，不要随手换成普通网络库； - 影刀日志使用
xbot.app.logging； - 页面元素、市场指令参数和业务口径没有验证时必须明确标注；
- 只改当前任务需要的代码，不做无关重构。
项目目录大致会变成：
真实影刀项目/
├── AGENTS.md
├── package.json
├── main.py
├── tools.py
└── 其他业务文件然后直接把这个目录交给 Agent，说明你希望它实现什么即可。复杂项目可以先让 Agent 生成一份 TASK.md，把目标、阶段、当前进度、未完成事项和风险写清楚；只改一个函数时不需要额外增加流程。
第二步：让浏览器插件成为 Agent 的“眼睛”
网页自动化最麻烦的地方，通常不是 Python 语法，而是页面到底有什么元素、按钮藏在哪一层、选择器是否稳定。
如果 Agent 能通过浏览器插件连接到你已经打开并授权的页面，它就可以辅助完成：
查看页面结构确认 iframe、弹窗、表格和按钮层级。
测试元素定位优先选择稳定属性、文本和局部范围。
探索操作流程验证点击、输入、等待和状态变化。
写回项目代码把验证过的元素和动作交给影刀执行。
这会比“你截一张图，Agent 猜按钮在哪里”可靠得多。但浏览器插件也不是全自动保证：登录状态、风控、动态页面、影刀浏览器对象和真实业务结果，仍然要在对应环境里验证。
第三步：把外部修改同步回影刀
Agent 在项目目录写完 .py 文件后，还需要让影刀认识这些代码流程。知识库根目录提供了 shadowbot_sync_tool.py，用于：
- 把尚未登记的 Python 文件写入
package.json； - 自动发现入口文件引用的辅助模块；
- 使用影刀 Python 编译入口文件和辅助模块。
调用时要同时区分“知识库工具路径”和“真实影刀项目路径”：
python "C:\\path\\to\\xbot-AI-docs\\shadowbot_sync_tool.py" ^
--project-dir "%LOCALAPPDATA%\\ShadowBot\\users\\<user_id>\\apps\\<app_id>" ^
prepare main.pyprepare 成功，说明流程登记和编译准备已经完成；它不等于页面操作、接口参数或整套业务已经在影刀中跑通。最后一步永远是回到影刀编辑器运行并检查结果。
知识库怎么继续更新
知识库不是整理一次就结束。影刀新增能力、项目遇到新问题、市场指令参数发生变化，都可能产生新的资料。
我现在保留两种更新方式。
方式一：让 Agent 分析指令后补库
遇到官方内置指令或市场指令没有清楚的编码版说明时，可以让 Agent 阅读允许查看的本地实现和调用信息，分析：
- 真实导入路径和调用入口；
- 参数名、默认值和必要类型；
- 返回值与异常表现；
- 一个最小可用示例；
- 还没有运行验证的部分。
然后把结论补充到 xbot-api-docs/docs/，示例放进 examples/，必要时同步更新 llms.txt 索引。不能公开的账号、Token、个人路径和完整运行包源码不能写进仓库。
方式二：直接把已知结论告诉 AI
如果我已经通过影刀运行确认某个参数或坑点，也可以直接告诉 Agent：
把这次验证结果补充进影刀知识库，写明正确用法、错误表现、最小示例和依据；不确定的部分放到待验证事项。
这样做的重点不是让文档越来越长，而是把下一次还会重复遇到的问题留下来。
为什么把它做成一个系列
这篇文章先把完整链路讲清楚，但其中每个环节都值得单独展开。后续可以继续补充：
- Agent 如何连接影刀项目与只读知识库；
- 如何用浏览器插件探索页面、寻找稳定元素定位；
- 如何分析市场指令和内置指令，并整理成可用 API 文档；
shadowbot_sync_tool.py的同步边界和排错方式；- 一个真实影刀项目如何从需求一直开发到编辑器内验证。