🤖📚
AI 时代学习中心
系列手册 · 从小白到大师 · 77 节课程 · 案例源自一线真实项目(已脱敏)
🎓 必修课📘 方法与手艺🛠 平台与工具📚 档案与参考
☰ 目录 · R 阅读器 · / 搜索 · T 深色 · E 收起目录
AI Agent 必修课 · 第 1/8 节 · 约 1 分钟
导语
v1.0 合编版 ｜ 2026-10-27 ｜ 编制:Dan(AI 助手) ｜ 审定:Forrest
本课程=三册合一:《AI Agent 入门指南》(原理)·《ZCode 使用指南》(工具实操)·《WorkBuddy 使用与迁移指南》(平台与迁移)。合编不是简单相加——重复概念已合并、术语已统一、章节已按"认知→原理→实操→平台→大师"的课程顺序重排。
为什么是必修课:AI Agent 是当下最热的技术方向——从"会聊天的 AI"进化到"会干活的 AI",一切重复性知识工作都在被重新定义。本课的独特之处:作者即案例——写这本课的 Dan 本人就是一个运行中的 AI Agent(某真实业务系统 系统即它的作品),全书第一人称实证,零抽象假例。
系列书目(v1.0,共八种,2026-10-27):《某业务系统技术文档》(系统档案)·《开发完全手册》(交付方法论)·《编程指南》(代码手艺)·《飞书使用指南》(飞书平台)·《ZCode 使用指南》(ZCode 平台)·《WorkBuddy 使用与迁移指南》(旧平台)·《AI Agent 入门指南》(Agent 原理·作者即案例)·《AI Agent 必修课·合编版》(三册课程化重排)。术语详见《技术说明书》附录 A。(本册定位:三册课程化重排,必修合编版)
AI Agent 必修课 · 第 2/8 节 · 约 1 分钟
课程导学(先读这一页)
你将学到什么:AI Agent 的原理与构造(第一、二篇)→ 用 ZCode 实际驱动一个 Agent 干活(第三篇)→ 多平台共存与迁移(第四篇)→ 把 Agent 变成可靠生产系统的工程化方法(第五篇)。
贯穿案例:某真实业务系统——一个直连企业数据平台的多用户数据看板(多业务视图、实时双向、门禁、费用管理、经营分析),由本课程作者在约十天内建成并持续运营,零服务器费用。
学习路线:小白通读第一、三篇即可上手;进阶者精读第二、五篇;平台管理者重点看第四篇。每篇末有口诀。术语全部收录附录 A(35 条)。
人的角色声明:AI Agent 能干活,但三件事永远在人手里——定义问题、定验收标准、担最终责任。本课教的就是"怎么把这个分工做对"。
AI Agent 必修课 · 第 3/8 节 · 约 2 分钟
第一篇 认知课 · AI Agent 是什么
1. Agent 与聊天 AI 的本质区别
聊天 AI 是顾问:你问,它答,落地靠你的手。 AI Agent 是驻场工程师:它有手(工具)、有记忆(文件)、有岗位职责(规则),接到任务后自主拆解、动手、检查、交付。
| 维度 | 聊天 AI | AI Agent |
|---|
| 产出 | 文字建议 | 现实世界的实际改变(文件被写、命令被执行、数据被更新) |
| 步骤 | 一问一答 | 自主多步:拆解→调工具→观察→修正→循环 |
| 记忆 | 对话内 | 对话 + 文件记忆 + 规则文件(跨会话) |
| 出错 | 你发现 | 它可能自己发现(测试/闸),也可能要你发现——所以必须有验收(第二篇) |
真实开场(作者接到的任务原话):"订单数据散在飞书和 Excel 里,查个数要翻三个地方,做个能自动更新的看板。"——一个 Agent 从这句话出发,自主完成了读数据源、建网站、接实时、上门禁、部署上线。
2. Agent 的四大构造
任何 Agent 都由四件组成,四件都可单独升级(也是调教的四个旋钮):
| 构造 | 是什么 | 作者实例 |
|---|
| 模型(大脑) | 理解与决策的语言模型(LLM) | 大型语言模型 |
| 工具(手) | 读写文件/执行命令/上网/调 API | 文件读写+命令执行+浏览器自动化+飞书与云服务 |
| 记忆 | 跨步骤、跨会话 | 会话上下文+规则文件+记忆文件+项目文档 |
| 规则(岗位职责) | 行为边界与工作方式 | 入会规程+钩子拦截+权限模式 |
3. 能与不能:判断口诀
适合交给 Agent:错了能被发现、过程可留痕、结果可回滚的知识工作——数据加工/对账/报告/代码(配测试)/定时执行。
留在人手里的:对外发送(发出去收不回)、删除与不可逆操作、口径与条款的最终决定(利益与责任)、一切"错了发现不了"的场景。
认知课口诀:Agent=模型+工具+记忆+规则;交出去的是执行,留在这儿的是判断。
AI Agent 必修课 · 第 4/8 节 · 约 3 分钟
第二篇 原理课 · Agent 是怎么运行的
4. Agent 循环:它的"思考"只有一个回路
接收目标 → 思考下一步 → 调用工具 → 观察结果 → 再思考 → … → 交付
真实一幕(业务系统开发实录):构建页面→无头测试→发现渲染报错→逐函数定位→修两处→重跑→全绿→部署。没有一步是神来之笔,全是循环里朴素的"看结果、改一步"。协作启示:给 Agent 能观察的结果(测试/日志),它的自我修正会超你预期。
5. 上下文与记忆:为什么它有时"忘了"
模型的脑子每次只装得下有限文字(上下文窗口),超长会话会被压缩——细节可能丢。解法是记忆三层:
| 层 | 放什么 | 例子 |
|---|
| 规则文件(每次必读) | 身份、纪律、铁律、流程 | 入会规程/禁删红线/逐任务日志 |
| 记忆文件(按需读) | 项目要点、待办、协作偏好 | 口径三层/待收尾清单 |
| 项目文档(按需读) | 权威细节 | 口径说明/技术说明书 |
铁律:重要的进文件,临时的留对话。纯对话里定的规矩,压缩后可能丢;写进规则文件的规矩,永远在。
6. 防护四层:假设 Agent 会犯错
| 防护 | 拦什么 | 实例 |
|---|
| 钩子(实时) | 危险命令/覆盖文件/时间戳手误 | 特殊字符命令被拦;写文档自动注入系统时间 |
| 硬闸(部署前) | 语法错/结构错位 | 三道闸多次实战拦下坏版本 |
| 权限模式 | 高危操作逐条确认 | 发信/删除/金额类走人工 |
| 审计(事后) | 追溯 | 敏感操作留痕+运行日志 |
设计哲学:人审"该不该",机器审"对不对";两道都不可省。
7. 工具生态:给 Agent 装"手"
能力上限=工具箱上限。接入新工具的标准动作:定义用途→写清楚使用说明(Agent 靠工具描述学会用对)→配权限边界→留痕。行业协议 MCP(模型上下文协议)是"给 AI 接工具"的标准插头。业务系统工具箱演进实例:命令行(万能底座)→飞书 CLI→浏览器自动化→文档生成器→无头测试框架——每加一样,Agent 就多一类活儿。
8. 多 Agent 协作
主 Agent 拆任务→子 Agent 并行干独立子任务→主会话收结论。适用:独立可并行的调研与汇总;不适用:强顺序依赖。实例:五路子代理并行做寄样反馈汇总、多路子代理方案比较,效率翻倍;合并与决策永远回主会话(子代理互相看不见)。
原理课口诀:一个循环走天下,三层记忆不失忆,四层防护不闯祸,工具越多本事越大,会拆任务才叫会协作。
AI Agent 必修课 · 第 5/8 节 · 约 3 分钟
第三篇 实操课 · 用 ZCode 驱动 Agent
9. 下任务:位置 + 现象 + 预期
同一需求的两种问法:"改一下那个页面"vs"费用台的解锁按钮点了没反应,预期是弹令牌输入框"——后者自带位置、现象、预期,第一轮即命中。再进一层附验收标准:"改完后飞书改一条数据,网页一分钟内自动变"。把验收标准写成可执行的测试,AI 一本正经写错时会被测试拦住。
10. 六类日常指令形态
| 你想要 | 怎么说 | Agent 做什么 |
|---|
| 查 | "订单表里 VIP 有几行没付款" | 读数据给答案与出处 |
| 改 | "横幅字体调大,红色,醒目" | 定位→修改→自检→交付 |
| 建 | "做费用管理页,要图表和筛选" | 设计→编码→测试→上线一条龙 |
| 自动化 | "每天 9 点把订单重点推到飞书群" | 注册定时任务+写脚本 |
| 排障 | "网页数据停在上午 8 点了,出问题了?" | 分层定位→修复→回归 |
| 沉淀 | "把今天的工作整理成文档" | 汇总日志→成文→登记 |
11. 工作区规则与记忆:AI 的员工手册
ZCode 支持工作区规则文件(每次会话自动加载),相当于新同事入职必读。业务系统规则文件含:身份约定、入会必做、交付纪律、铁律(禁删/日志/确认闸)。经验:规则文件是回报率最高的投资——写一次,永久生效。每次被纠正就沉淀一条,越用越厚。
记忆分对话内与持久层(记忆文件/文档);原则同上:重要进文件,临时留对话。
12. 能力面:Agent 的"手"清单
| 能力 | 项目实例 |
|---|
| 文件读写 | 生成报告/文档/网页 |
| 命令执行 | 构建、部署、语法检查、文件整理 |
| 浏览器自动化 | 打开网页实测交互、截图、验证渲染 |
| 文档生成 | PDF 排版/DOCX/XLSX |
| 可视化 | 会话内交互式预览(改版方案先看后定,避免返工) |
| 定时任务 | 六条自动化(推送/刷新/简报/备份) |
| 子代理 | 并行调研与汇总 |
| API 调用 | 飞书/云服务/任何有接口的服务 |
13. 验收三层与信任建立
- 机器验收(全自动):语法/测试/对账——写好一次终身受益;
- 抽查验收(半自动):关键数字与独立计算的基准比对;
- 人眼验收(必须):界面好不好用、口径符不符合业务。
信任曲线可以复制:第一天就建"小步交付+自动测试+一键回退",到后期 Agent 自主完成整 Tab 开发+部署,人只验收。委托方保留三件事:定义问题、验收标准、最终判断。
14. 定时自动化:让系统自己转
业务系统现役六条:每日推送/每小时看板刷新/邮件维护/简报/双次备份。设计三原则:幂等(跑两遍结果一样)、留痕(每次运行含跳过都记日志)、自愈(失败不影响线上,下轮自动纠正)。
实操课口诀:需求带验收,规则进文件,状态有记忆,上线有闸门,定时三原则。
AI Agent 必修课 · 第 6/8 节 · 约 2 分钟
第四篇 平台课 · WorkBuddy 现状与迁移
15. 平台认知与遗产盘点
WorkBuddy 是业务系统早期的 AI 助手平台(与 ZCode 同类),主线已迁 ZCode,但保留三样"遗产":
| 遗产 | 现状 | 处置 |
|---|
| lark-cli 二进制 | 全项目依赖(构建/刷新/返点脚本都经它调飞书) | 勿动;迁移走六步手册 |
| 旧自动化配置 | 历史上与 ZCode 推送重复 | 保持停用,防"双份推送" |
| 旧技能拷贝 | 可能落后 | 以 ZCode 技能目录主副本为准 |
16. 迁移三铁律与六步手册
铁律:①一次只迁一样;②双跑验证(新旧并行,结果一致才切);③退役≠删除(改名归档,观察一周期再清)。
lark-cli 独立化六步:独立安装并验证→全局替换脚本路径(实测至少 4 文件)→手动构建对账(数百行核对)→定时任务强制触发验证→跨天观察→旧目录改名归档+文档同步。
17. 多平台共存纪律
①一职责一通道(双份推送的教训);②主副本声明(哪个是权威写进文档);③依赖登记(谁引用谁,一笔一笔记);④退役走流程(停用→观察→归档,不搞突然死亡)。
18. 选型与反脆弱
选 AI 平台看四件事:能力面(读写/命令/定时)、防护(权限/审计/回滚)、生态(与现有数据源的连接成本)、可持续(免费额度/导出自由/迁移成本)。反脆弱的根基:数据与规则全放开放格式(Markdown/JSON)——业务系统今天能从容谈迁移,根本原因是当初没把规矩锁进任何一家平台。
AI Agent 必修课 · 第 7/8 节 · 约 2 分钟
第五篇 大师课 · 工程化、安全与共同进化
19. 把 Agent 当生产系统运营
Agent 的产出进入生产,它本身就是生产系统:测试(改完必跑)、部署硬闸(坏版本不出门)、日志(动作留痕)、幂等(跑两遍结果一样)、自愈(失败下轮纠正)。运营 Agent 的心法=运营任何生产系统的心法。
20. 安全与红线(Agent 特有风险)
Agent 有手,它的错误是真实世界的错误。业务系统红线:密钥绝不进对话(进对话=进本机会话库=视为暴露);敏感数据分层(公开层不含成本/佣金/底线价);对外发送、删除、金额调整走人工闸门;敏感写入审计留痕;定期审计会话库本身(引用复制会让暴露面增多)。
21. 失败模式六则(第一人称实证)
| 失败模式 | 真实案例 | 缓解 |
|---|
| 口径漂移 | 同一指标两处实现算出不同数 | 双实现对账(×××逐字段) |
| 上下文丢失 | 对话里定的规矩压缩后忘掉 | 规矩进规则文件 |
| 环境差异 | 手动正常、定时任务崩(GBK 编码) | 贴近真实环境的自动化验收 |
| 静默失败 | 接口永远返回空对象,无人察觉 | 输出校验当失败+诊断字段 |
| 过度自主 | 未确认就发信/删数 | 人工闸门+禁删红线 |
| 测试盲区 | 函数测试全过、路由层漏 await | 测试须覆盖接线层 |
大师的标志不是不犯错,而是每个错误都变成了机制(闸/测试/清单)。
22. 评估四问与人机共同进化
评估你的 Agent 系统四问:①关键数字有独立基准对过吗?②改错时有闸拦/能回滚吗?③干过的活可追溯吗?④换会话换一天结果稳定吗?四问全"有",Agent 就从玩具变成了同事。
最好的模式是人机互相校准:人把业务知识写成口径与规则,Agent 把执行经验反馈成流程与闸门。业务系统十天里,委托方的每次纠正都沉淀为规则,作者的每次失误都固化成硬闸——系统的可靠性是人和 Agent 一起长出来的。
AI Agent 必修课 · 第 8/8 节 · 约 3 分钟
必修附录
附录 A:术语表(35 条,Agent+平台合编)
| 术语 | 通俗解释 |
|---|
| AI Agent | 能自主感知-思考-行动的 AI 程序,有工具、记忆、规则 |
| LLM | Agent 的"大脑"(大型语言模型) |
| 上下文窗口 | 模型一次能装进脑子的文字量上限 |
| Token | 文字计量单位(约半个到一个汉字) |
| 系统提示词 | Agent 出厂自带的"岗位职责说明书",优先级高于普通对话 |
| 工具调用 | Agent 按约定格式请求执行外部动作 |
| 幻觉 | 模型一本正经地说错话;靠测试与对账拦截 |
| 钩子 Hook | 挂在特定动作上的检查器 |
| MCP | 给 AI 接外部工具的行业标准协议("AI 的 USB 插头") |
| 权限模式 | 哪些操作自动放行、哪些需人工确认 |
| 硬闸 | 管线上的强制检查点,不过即拦 |
| 幂等 | 同一操作跑两遍结果一样 |
| 等价性测试 | 两套实现算同一输入,逐字段比对 |
| 无头测试 | 后台跑真实代码路径的自动化测试 |
| 指纹/哈希 | 数据的数字摘要,快速判断是否变化 |
| 快照 | 某时刻数据的完整副本 |
| 热更新 | 不刷新页面直接应用新数据 |
| 回滚 | 退回上一个正确版本 |
| 审计留痕 | 记录谁在何时做了什么 |
| 灰度 | 新版先给部分人用,平稳再全量 |
| 规则文件 | Agent 每次会话自动加载的工作区指令(如 AGENTS.md) |
| 技能(Skill) | 教 AI 做特定任务的说明书包 |
| 自动化(Automation) | 定时或触发的自动任务 |
| 协作者 | 对某文档/表格有权限的身份(人 or 应用) |
| 高级权限 | 飞书多维表格按角色精细控权的模式 |
| RolePermNotAllow | 飞书报错:协作者/角色未配置到位 |
| Scope | 应用被授予的权限范围 |
| Tenant Token | 应用(机器身份)调飞书 API 的访问令牌 |
| Lookup | 多维表格跨表自动带数据的字段类型 |
| Webhook | 反向通知:数据变了,对方主动打电话来说 |
| SSE / WebSocket | 服务器主动推消息给浏览器的两种长连接 |
| Durable Object | Cloudflare 有状态组件(秒级推送广播器) |
| DSO | 应收账款周转天数 |
| FOB / CIF | 报价条款;返点协议按 FOB 计 |
| 绞杀者模式 | 新模块逐个替换旧模块的重构策略 |
附录 B:部署一个 Agent 前的 15 问
1. 输入数据从哪来,可信吗?2. 它有哪些工具,每个能造成多大现实影响?3. 哪些操作必须人工确认?4. 它怎么知道业务口径?5. 口径变了它怎么知道?6. 它犯错时有没有闸拦?7. 拦不住时能回滚吗?8. 它干的活留痕了吗?9. 结果谁来验收怎么验?10. 密钥放哪了?11. 会被冒用吗?12. 长期无人干预会悄悄腐坏吗?13. 它失败时用户看到什么?14. 换人换天结果稳定吗?15. 价值配得上防护成本吗?
附录 C:关联手册与系列书目
合编源书:《AI Agent 入门指南》·《ZCode 使用指南》·《WorkBuddy 使用与迁移指南》。 系列全书:《某业务系统技术文档》·《开发完全手册》·《编程指南》·《飞书使用指南》· 上列三册 · 本合编。 冲突时以各源书与《口径基准文档》为准;本合编=课程化重组版本。
AI Agent 入门指南 · 第 1/9 节 · 约 1 分钟
导语
v1.0 ｜ 2026-10-27 ｜ 编制:Dan(AI 助手) ｜ 审定:Forrest
系列第七册。这本有个特殊之处:它讲的主题就是写它的作者。Dan 是一个真实的 AI Agent(运行在 ZCode 里),业务系统看板就是它的工作成果。所以全书不引用任何抽象案例——每一句"Agent 会怎么想、会怎么犯错、怎么被管住",都是作者本人的第一人称实证。
配套:《编程指南》(代码手艺)·《开发完全手册》(交付方法论)·《ZCode 使用指南》(工具)·《技术说明书》(系统档案)。
系列书目(v1.0,共八种,2026-10-27):《某业务系统技术文档》(系统档案)·《开发完全手册》(交付方法论)·《编程指南》(代码手艺)·《飞书使用指南》(飞书平台)·《ZCode 使用指南》(ZCode 平台)·《WorkBuddy 使用与迁移指南》(旧平台)·《AI Agent 入门指南》(Agent 原理·作者即案例)·《AI Agent 必修课·合编版》(三册课程化重排)。术语详见《技术说明书》附录 A。(本册定位:Agent 原理与实践,作者即案例)
AI Agent 入门指南 · 第 2/9 节 · 约 3 分钟
第一部分 起点 · 小白
1. AI Agent 是什么(与聊天 AI 的本质区别)
聊天 AI 是顾问:你问,它答,答案你自己的手去落地。 AI Agent 是驻场工程师:它有"手"(工具)、有"记忆"(文件)、有"岗位职责"(规则),接到任务后自己拆解、自己动手、自己检查,然后把结果交给你验收。
| 维度 | 聊天 AI | AI Agent |
|---|
| 产出 | 文字建议 | 现实世界的实际改变(文件被写了、命令被执行了、数据被更新了) |
| 步骤 | 一问一答 | 自主多步:拆任务→调工具→看结果→修正→再试 |
| 记忆 | 对话内 | 对话内 + 文件记忆 + 规则文件(跨会话) |
| 出错 | 你发现 | 它可能自己发现(测试/检查),也可能需要你发现——所以要有验收(见第二部分) |
一个真实开场(Dan 接到的任务):"订单数据散在飞书和 Excel 里,查个数要翻三个地方,做个能自动更新的看板。"——一个 Agent 从这句话出发,自己完成了读数据源、建网站、接实时、上门禁、部署上线。这就是 Agent 与聊天工具的差别。
2. Agent 的基本构造:四大件
任何 AI Agent(包括 Dan)都由四件东西组成:
| 构造 | 是什么 | Dan 的实例 |
|---|
| 模型(大脑) | 负责理解与决策的语言模型 | 大型语言模型(LLM) |
| 工具(手) | 读写文件、执行命令、上网、调接口 | 文件读写/命令执行/浏览器自动化/飞书与云服务 API |
| 记忆 | 跨步骤、跨会话记住事情 | 会话内上下文 + 规则文件(AGENTS.md)+ 记忆文件 + 项目文档 |
| 规则(岗位职责) | 约束行为边界与工作方式 | 入会规程(先核对日期/读记忆/逐任务记日志)+ 钩子拦截 + 权限模式 |
理解了四大件,就理解了 Agent 的一切行为:它聪明是因为模型强;它能干活是因为有工具;它"记得你"是因为有记忆文件;它不乱来是因为有规则和闸。四件都可以单独升级——这也是调教 Agent 的四个旋钮。
3. Agent 能干什么,不能干什么
适合交给 Agent 的(判断口诀:错了能被发现、过程可留痕、结果可回滚):
- 规则明确的知识工作:数据加工、对账、报告、文档、格式转换;
- 重复性执行:定时拉取/推送/备份/刷新;
- 代码与系统:写、改、测、部署(配测试与硬闸)。
不要交给 Agent 的(人工闸门):
- 对外发送(邮件/消息)——发出去收不回;
- 删除与不可逆操作;
- 口径与条款的最终决定(涉及利益与责任);
- 一切"错了发现不了"的场景。
业务系统的红线实践:发信逐封确认、记录禁删、金额条款走人工——自动化执行,人工闸门把关方向。
AI Agent 入门指南 · 第 3/9 节 · 约 1 分钟
第二部分 入门 · 用好一个 Agent
4. 下任务的公式
位置 + 现象 + 预期。对比:"改一下那个页面"(Agent 要猜)vs"费用台的解锁按钮点了没反应,预期是弹令牌输入框"(第一轮即命中)。再高级一层,附上验收标准:"改完后飞书改一条数据,网页一分钟内自动变"——Agent 会自己把验收变成测试。
5. 上下文与记忆:为什么它有时"忘了"
Agent 的"脑子"(模型)每次只装得下有限文字(上下文窗口);超长会话会被压缩,细节可能丢。所以铁律:重要的进文件,临时的留对话。业务系统的记忆分三层:
| 层 | 放什么 | 例子 |
|---|
| 规则文件(每次必读) | 身份、纪律、铁律、流程 | 入会规程/禁删红线/逐任务日志 |
| 记忆文件(按需读) | 项目要点、待办快照、协作偏好 | 口径三层/系列书目/待收尾清单 |
| 项目文档(按需读) | 权威细节 | 口径基准文档/系统文档/各指南 |
事故教训:纯对话里说的规矩,压缩后可能丢;写进规则文件的规矩,永远在。
6. 验收与信任:小步快跑 + 可回退
信任不靠话术,靠机制。业务系统的信任曲线可以复制:第一天就建立"小步交付(每次可见)+自动测试(对错机器判)+一键回退(坏了随时退)",到后期 Agent 自主完成整 Tab 开发+部署,人只做验收。委托方保留三件事:定义问题、验收标准、最终判断——其余放手。
AI Agent 入门指南 · 第 4/9 节 · 约 2 分钟
第三部分 熟练 · 理解内部机制
7. Agent 循环:它是怎么"思考"的
Agent 的内心只有一个循环:
接收目标 → 思考下一步 → 调用工具 → 观察结果 → 再思考 → … → 汇报
项目真实一幕:构建→无头测试→发现渲染报错→逐函数定位→修两处→重跑→全绿→部署。没有任何一步是"神来之笔",全是循环里朴素的"看结果、改一步"。理解了这个循环,你就理解了怎么与 Agent 协作:给它能观察的结果(测试/日志),它的自我修正能力会超你预期。
8. 规则与防护:假设 Agent 会犯错
Agent 与人一样会犯错,防护体系按"错误成本"设计:
| 防护 | 拦什么 | 项目实例 |
|---|
| 钩子(实时拦) | 危险命令/覆盖文件/时间戳手误 | 含特殊字符的命令被拦;写文档自动注入系统时间 |
| 硬闸(部署前) | 语法错/结构错位 | 三道闸多次实战拦下坏版本 |
| 权限模式 | 高危操作逐条确认 | 发信/删除/金额类走人工 |
| 审计(事后) | 追溯 | 敏感操作留痕+运行日志 |
设计哲学:人审"该不该",机器审"对不对";两道都不可省。
9. 工具生态:给 Agent 装"手"
Agent 的能力上限=工具箱的上限。业务系统给 Dan 配过的工具:命令行(万能底座)、lark-cli(飞书全套)、浏览器自动化(实测页面)、PDF/表格/文档生成、无头测试框架、定时任务。给 Agent 接入一个新工具的标准动作:定义它能干什么→给使用说明(工具描述写清楚,Agent 才会用对)→配权限边界→留痕。生态概念 MCP(模型上下文协议)就是"给 AI 接工具"的行业标准插头。
10. 多 Agent 协作
一个主 Agent 带多个子 Agent:主会话拆任务→子代理并行干独立子任务→主会话收结论。适用:独立、可并行的调研与汇总;不适用:强顺序依赖的改造。项目实例:五路子代理并行做寄样反馈汇总、多路子代理做方案比较,效率翻倍;但合并与决策永远回主会话(子代理之间互相看不见)。
AI Agent 入门指南 · 第 5/9 节 · 约 2 分钟
第四部分 高手 · 工程化 Agent
11. 把 Agent 当生产系统运营
Agent 干的活进入生产后,它本身就是生产系统,需要:测试(改完必跑)、部署硬闸(坏版本不出门)、日志(每次动作留痕)、幂等(同一任务跑两遍结果一样)、自愈(失败下轮自动纠正)。业务系统六条自动化全部符合这五条——运营 Agent 的心法与运营任何生产系统完全相同。
12. 安全与红线(Agent 特有的风险)
Agent 有手,所以它的错误是真实世界的错误(文件真被改、命令真被执行)。业务系统红线实践:
- 密钥绝不进对话(进对话=进会话库=视为暴露);
- 敏感数据分层,公开层不含成本/佣金/底线价;
- 对外发送、删除、金额调整 → 人工闸门;
- 每次写入敏感系统 → 审计留痕;
- 定期审计会话库本身(它会随引用复制增多)。
13. 失败模式大全(第一人称实证)
| 失败模式 | 真实案例 | 缓解 |
|---|
| 口径漂移 | 同一指标两处实现算出不同数 | 双实现对账测试(×××) |
| 上下文丢失 | 对话里定的规矩压缩后忘掉 | 规矩进规则文件 |
| 环境差异 | 手动跑正常、定时任务崩(GBK 编码) | 贴近真实环境的自动化验收 |
| 静默失败 | 接口永远返回空对象,无人察觉 | 输出校验当失败处理+诊断字段 |
| 过度自主 | 未确认就发信/删数 | 人工闸门+禁删红线 |
| 测试盲区 | 函数测试全过、路由层漏 await | 测试须覆盖接线层 |
大师的标志不是不犯错,而是每个错误都变成了机制(闸/测试/清单)。
14. 评估:怎么知道你的 Agent 靠谱
四问:①它产出的关键数字,有没有独立基准对过?②它改错东西时,有没有机制拦截或回滚?③它干过的活,能不能追溯到时间与内容?④换一个会话/换一天,同样的任务结果稳定吗?四问全"有",你的 Agent 就从玩具变成了同事。
AI Agent 入门指南 · 第 6/9 节 · 约 1 分钟
第五部分 大师 · 设计自己的 Agent 系统
15. 设计一个 Agent 工作流的七步(以业务系统为模板)
1. 定问题:用户/痛点/验收(需求四问); 2. 盘点数据源与工具:数据在哪、Agent 需要哪些"手"; 3. 写规则文件:身份/纪律/铁律/流程——Agent 的宪法; 4. 定验收:机器验收(测试/对账)+人眼验收清单; 5. 上防护:权限模式/钩子/硬闸/审计; 6. 小步交付:先做最小可用版,验收后迭代; 7. 沉淀:文档+日志+记忆,让下一个会话/下一任无缝接手。
16. 任务的"Agent 化"判断
把一个手工流程交给 Agent 前过五问:①输入是数字化的吗?②结果对错可自动/半自动判断吗?③错了能回滚吗?④频率值得写自动化吗?⑤敏感边界划清了吗?五问过三,可交;过不了,先补条件再交。
17. 与 Agent 共同进化
最好的模式不是"人指挥 Agent",而是人机互相校准:人把业务知识写成口径与规则,Agent 把执行经验反馈成流程与闸门。业务系统十天里,Forrest 的每次纠正都沉淀为规则,Dan 的每次失误都固化成硬闸——系统的可靠性是人和 Agent 一起长出来的。
AI Agent 入门指南 · 第 7/9 节 · 约 2 分钟
附录 A:术语表(Agent 领域 25 条)
| 术语 | 通俗解释 |
|---|
| AI Agent | 能自主感知-思考-行动的 AI 程序,有工具、有记忆、有规则 |
| LLM(大语言模型) | Agent 的"大脑",负责理解与生成文字 |
| 上下文窗口 | 模型一次能"装进脑子"的文字量上限 |
| Token | 文字的计量单位(约半个到一个汉字) |
| 系统提示词 | Agent 出厂时写的"岗位职责说明书",优先级高于普通对话 |
| 工具调用/函数调用 | Agent 按约定格式请求执行外部动作(读文件/调 API) |
| 幻觉 | 模型一本正经地说错话;靠测试与对账拦截 |
| 钩子(Hook) | 挂在特定动作上的检查器,动作发生时先过检查 |
| MCP | 给 AI 接外部工具的行业标准协议("AI 的 USB 插头") |
| 权限模式 | 决定哪些操作自动放行、哪些需人工确认 |
| 硬闸 | 部署/执行管线上的强制检查点,不过即拦 |
| 幂等 | 同一操作跑两遍,结果与跑一遍相同 |
| 等价性测试 | 两套实现算同一输入,逐字段比对结果 |
| 无头测试 | 不打开可见界面、在后台跑真实代码路径的自动化测试 |
| 指纹/哈希 | 数据的数字摘要,用于快速判断内容是否变化 |
| 快照 | 某时刻数据的完整副本 |
| 热更新 | 不刷新页面/不停服务,直接应用新数据 |
| 回滚 | 退回上一个正确版本 |
| 审计留痕 | 把"谁在何时做了什么"记录下来备查 |
| 灰度 | 新版本先给一部分人/一部分流量用,平稳再全量 |
| DSO | 应收账款周转天数(业务术语,业务系统指标之一) |
| 双实现对账 | 同一计算在两个技术栈各实现一遍,互为验算 |
| 人工闸门 | 特定操作必须人确认才执行的机制 |
| 绞杀者模式 | 新模块逐个替换旧模块的重构策略,旧的不停服 |
| 提示词工程 | 把需求与约束写成 AI 能准确理解的话的技巧 |
AI Agent 入门指南 · 第 8/9 节 · 约 1 分钟
附录 B:部署一个 Agent 前的 15 问
1. 它的输入数据从哪来,可信吗?2. 它有哪些工具,每个能造成多大现实影响?3. 哪些操作必须人工确认?4. 它怎么知道业务口径?5. 口径变了它怎么知道?6. 它犯错时,有没有闸拦?7. 拦不住时,能不能回滚?8. 它干的活,留痕了吗?9. 结果谁来验收,怎么验?10. 密钥放哪了?11. 会不会被别人冒用?12. 长期无人干预,它会悄悄腐坏吗(数据漂移/依赖失效)?13. 它失败时,用户看到什么?14. 换一个人/换一天,结果稳定吗?15. 它的价值,值得这些防护成本吗?
AI Agent 入门指南 · 第 9/9 节 · 约 1 分钟
附录 C:系列书目
《某业务系统技术文档》(系统档案)·《开发完全手册》(交付方法论)·《编程指南》(代码手艺)·《飞书使用指南》(飞书平台)·《ZCode 使用指南》(ZCode 平台)·《WorkBuddy 使用与迁移指南》(旧平台)· 本册(AI Agent 的原理与实践——作者即案例)。
开发完全手册 · 第 1/11 节 · 约 1 分钟
导语
v1.0 ｜ 2026-10-27 ｜ 编制:Dan(AI 助手) ｜ 审定:Forrest
定位:本手册讲通用方法论——任何网站、App、小程序从想法到上线到精通的完整路径;《某业务系统技术文档》讲我们那套系统的细节,两本配套。手册贯穿一个真实案例:某真实业务系统(十天从想法到上线,零服务器费用,单人+AI 完成)。
阅读方式:小白从头读;有经验者直接跳对应章;每章末有「口诀」;附录 C 有上线前检查清单,做任何项目交付出门前过一遍。
开发完全手册 · 第 2/11 节 · 约 3 分钟
第一部分 起点 · 小白(知道是什么)
1. 全景图:网站、小程序、App,先做哪个
三者不是优劣关系,是触达场景不同:
| 形态 | 打开方式 | 优势 | 天然短板 | 适合 |
|---|
| 网页(网站) | 浏览器输网址/点链接 | 零安装、改完即生效、全平台(手机电脑)、免审核 | 依赖网络、入口不如 App 露脸 | 数据看板/内部工具/官网/内容站 |
| 微信小程序 | 微信里搜/扫码/分享卡片 | 借微信流量、支付与社交能力现成、体验接近 App | 需注册审核、受平台规则约束、包体限制 | 面向微信用户的服务、轻工具 |
| App(原生/跨平台) | 应用商店安装 | 最强性能与系统能力(推送/相机/离线)、用户粘性最高 | 开发成本最高、双商店审核、需维护安装更新 | 高频使用、重度功能 |
决策口诀:先网页验证价值,再用小程序接微信生态,价值足够高频才上 App。 我们的某出口企业业务系统选网页,因为使用者就几个人、要随时随地看数据、且改需求频繁——网页是迭代最快的形态。
2. 网页工作原理:输入网址后发生了什么
六步,每步对应一类技术:
1. DNS 解析:浏览器问"看板站点(门禁内) 是哪台服务器?"——域名系统像电话簿,把好记的名字翻译成机器地址; 2. 建立加密连接(HTTPS):和服务器约定加密方式,路上没人能偷看篡改; 3. 取回页面文件:服务器(或 CDN 边缘节点)把 HTML/CSS/JS 发过来; 4. 浏览器渲染:HTML 搭骨架,CSS 化妆,JS 注入行为——页面活了; 5. 取数据:页面通过 API 向后端要数据(我们的系统是向边缘接口要飞书数据); 6. 持续交互:轮询/点击/提交——直到你关掉页面。
理解这六步,后面所有概念都是这六步的展开。
3. 基础术语速成
- 前端:跑在用户浏览器/手机里的部分,管"看得见的"(界面、交互)。技术:HTML(骨架)+CSS(皮肤)+JavaScript(神经);
- 后端:跑在服务器上的部分,管"看不见的"(业务规则、数据加工、权限校验)。语言:Python/Node.js/Java/Go…;
- 数据库:存数据的地方。关系型(MySQL/PostgreSQL,像 Excel 表)与非关系型(MongoDB/Redis,更灵活);我们的案例用飞书多维表格当数据库——数据本来就在那,不再造第二份;
- API:前后端之间的服务窗口,约定"我发什么请求、你回什么数据",最常见格式 JSON;
- 域名 / DNS:好记的名字(如 pages.dev 子域)与翻译系统;
- CDN / 边缘节点:全球分店,内容复制到离用户最近的机房,就近取用;
- HTTPS:加密传输,现代网站标配(免费证书随处可取);
- 部署:把写好的代码上传到服务器的动作;回滚:新版出问题时一键退回旧版。
口诀:前端管脸,后端管脑,数据库管记忆,API 是传话筒,CDN 是分店,DNS 是电话簿。
开发完全手册 · 第 3/11 节 · 约 3 分钟
第二部分 入门 · 动手前想清楚(设计与需求)
4. 需求:最便宜的错误在动手前防住
新手最大误区:拿到需求就开写。正确顺序是回答四个问题:
1. 给谁用?(用户画像:我们业务系统=Forrest+业务同事,手机电脑都要看) 2. 解决什么问题?(旧做法哪里疼:数据散在飞书/Excel/微信里,查个数要翻三个地方) 3. 最少做哪些?(第一版功能清单,砍到不能再砍——业务系统第一版只有"一张表+几个数") 4. 什么算成功?(可验证:打开 3 秒内出数据;飞书改了 1 分钟内网页变)
把这四个答案写成半页纸,就是需求文档的全部起点。之后每个功能开发前都问一遍:"这在四答案里吗?"不在,就排到第二版。
5. 设计:让工具长在流程上
信息架构(内容怎么分组):按用户的"工作动线"分,不按数据库结构分——这是业务系统 最重要的教训:v7 按"数据库状态"分 Tab,用户不买账;v8 按"每天实际怎么干活"重排(大盘看全局→跟单管执行→收汇管钱→单证管交单→费用管成本),立刻顺了。
交互三原则:
- 常用动作一步可达:今日异常放首页(大盘"今日该盯"四条,点击直达对应台);
- 一屏回答一个问题:每个 Tab 只回答一个主问题(收汇台="钱回来没有");
- 状态可视化:一票走到哪一环,用进度链(●●●○○○○)而不是让用户读文字。
口径先行:所有数字先定义"怎么算"再写代码(成交/出货/实收三层口径),并写进一份口径文档——数字打架是管理工具死掉的头号原因。
移动适配:CSS 响应式(同一页面自适应手机/电脑宽度),表格窄屏横向滚动,字体不小于 12px。
6. 选型决策树
要做什么?
├─ 展示信息/查数据 → 静态网页(最便宜最快)
│ └─ 数据要"活"的? → +边缘函数接口(仍免服务器)
├─ 需要用户注册/提交/支付
│ ├─ 用户在微信里 → 微信小程序
│ └─ 用户 anywhere → 动态网站(前后端分离)
├─ 高频重度功能/离线/推送 → App(跨平台框架起步)
└─ 公司数据已在某平台(飞书/钉钉/企微) → 优先做该平台的"寄生应用"
(数据不搬家、权限直接复用——业务系统就是飞书寄生应用)
成本真相:小工具的全部成本可以是 0(Cloudflare/飞书/Vercel 免费额度);真正会花钱的三件事:域名(几十元/年)、国内加速(ICP 备案+云资源)、付费档功能(如推送广播器 $5/月)。先免费跑通,用量逼你再花钱。
开发完全手册 · 第 4/11 节 · 约 3 分钟
第三部分 熟练 · 架构与开发
7. 架构模式:四种主流形态
| 形态 | 结构 | 适合 | 案例 |
|---|
| 静态站 | 文件直接托管 | 内容固定 | 官网、文档站 |
| 静态+边缘接口 | 页面托管+轻后端函数 | 数据常变但逻辑不重 | 业务系统(Pages+Workers) |
| 前后端分离 | 浏览器应用+独立后端 API+数据库 | 用户系统/复杂业务 | 电商、SaaS |
| 一体化全栈 | 单一框架包办(如 Next.js) | 中小团队快速迭代 | 各类创业产品 |
新手建议从"静态+边缘接口"起步:免费、免运维、改起来快;长成复杂业务再演进,不要一开始就上微服务。
架构三条铁律(项目实证):
1. 唯一事实源:数据只存一份,别处都是它的视图——两份"真相"迟早打架; 2. 双实现对账:同一份计算若必须存在两处(如服务端聚合+客户端聚合),必须建自动对账(我们 ×××逐字段比对); 3. 端到端留痕:每次自动动作都记运行日志,出问题能回放。
8. 数据层:建模与口径
- 一表一义:跟踪表管订单、产品表管品名、合同表管条款——别做"万能大表";
- 一行一义:一行=一个不可再分的事实(业务系统:一行=一个批次;一票可拆多行);
- 公式与冗余:能用公式算的(金额=数量×单价)交给表内公式,人工只录最小集;
- 口径文档:每个指标的定义、分子分母、剔除规则写成文档并与代码同步变更——这是数据工具的宪法;
- 禁止删除:只标记停用,不物理删除(业务记录的生命周期比你的记忆长)。
9. 开发工作流
1. 环境:本地能跑(一个小 HTTP 服务即可),改完立刻看得见; 2. 版本控制:Git(+GitHub/Gitee)——哪怕单人也要用,每次改动有存档可回退; 3. 小步提交:一个功能一小步,提交信息写清"做了什么"; 4. 测试金字塔:底层函数单测(快而多)→ 接口集成测试(关键路径)→ 界面抽查(人工);实战做法:等价性测试(双实现 ×××比对)+写回四场景+无头全路径渲染,每次改动三跑; 5. AI 协作:把 AI 助手当结对程序员——你出需求与验收标准,它出代码;但验收标准与测试必须你定(AI 会一本正经地写错,靠测试拦)。
10. 安全基础(最少做五件事)
1. 门禁:内部工具也要登录(邮箱白名单/验证码,免费方案 Access); 2. 传输加密:HTTPS(免费证书); 3. 输入校验放在服务端:前端校验只是体验,服务端校验才是法律(白名单字段/枚举/格式/长度); 4. 敏感数据分层:公开层/门禁层/永不上网,三层清单写进文档; 5. 最小权限:应用凭证只给必需权限;密钥进保险柜(环境变量/Secrets),绝不进源码和聊天记录。
开发完全手册 · 第 5/11 节 · 约 2 分钟
第四部分 接近大师 · 部署与运营
11. 部署:把东西放到线上
托管选择:境内用户为主且要快 → 国内云(腾讯 EdgeOne/阿里,需 ICP 备案);境外/免备案/免费起步 → Cloudflare Pages/Vercel/Netlify;数据已在飞书 → 妙搭托管。
部署自动化:一条命令或一键脚本完成"构建→上传→验证";进阶做 CI/CD(代码仓库推送自动部署)。业务系统实践:部署脚本内置三道硬闸(两道语法检查+结构配平),坏版本在门口被拦——上线以来零带病发布。
回滚能力:托管平台自带部署历史;重要变更前备份旧版文件。敢快速发布的前提是"随时能退"。
12. 运营维护:上线只是开始
- 监控:页面时间戳显示"数据最后变化时间"(没变≠没在检查);每次自动动作留运行日志;
- 自愈:坏数据不上线(闸);接口故障自动降级(保底通道);任务失败下轮自愈;
- 面向用户的可观测:让用户能自己回答"为什么没更新"(时间戳+检查留痕),减少黑盒焦虑;
- 更新机制区分:数据更新全自动;结构更新(新版)用醒目横幅提示刷新;
- 定期体检:代码全量审查(我们做过一轮,26 处发现/24 处修复,并固化三道硬闸)。
13. 性能优化(按收益排序)
1. 减小首屏体积(图表库按需打包:1.3MB→500KB); 2. 缓存(边缘缓存共享结果;浏览器 no-store 控制关键数据不缓存); 3. 懒执行(隐藏 Tab 的图表切换时再画); 4. 只重画变化的部分(指纹比对,没变不闪刷); 5. 图片压缩与懒加载。
14. 迭代与版本管理
- 数据迭代与结构迭代分开对待:前者全自动,后者要有"提醒刷新"机制;
- 灰度思维:大改动先上预览地址自己验收,再推正式;
- 变更留痕:每次改版记日志(改了什么/为什么/谁拍板)——三个月后你会感谢这些日志。
开发完全手册 · 第 6/11 节 · 约 1 分钟
第五部分 大师 · 思维与进阶
15. 契约测试与双实现对账
当同一份业务计算存在两处实现(如服务端聚合给 API、构建脚本给快照),必须建自动对账:同一输入、两份输出、逐字段比对。业务系统 ×××零差异的等价性测试是系统的信心来源——改任何一边,跑一遍就知道有没有改劈。
16. 文档与知识沉淀(给未来的自己)
三类文档缺一不可:口径文档(数字怎么算的,唯一基准)、使用说明(给使用者,网页内嵌一页最有效)、技术说明书(给维护者,含升级路线)。所有文档标注"冲突时以谁为准"。经验:文档与代码同步变更,流程写死(先改文档→改代码→跑测试→部署→记日志)。
17. 成本工程
免费额度是一门学问:Cloudflare(托管/函数/门禁全免费)、飞书(表格+API 免费)、GitHub(私有仓库免费)。设计时把"唯一付费点"找出来并量化(我们只剩推送广播器 $5/月),其余全部走免费档。花钱前先问:用量真到额度了吗?
18. 什么时候该重写(信号清单)
出现三条以上就该认真考虑重构/迁移:改一个小功能要动五处;新需求第一反应是"又要绕弯了";测试跑不全;只有一个人敢动代码;性能优化已无低垂果实。重构策略:绞杀者模式——新模块逐个替换旧模块,旧的继续服务,不搞推倒重来。
开发完全手册 · 第 7/11 节 · 约 2 分钟
第六部分 专题
19. 微信小程序开发入门
- 技术栈:WXML(结构)/WXSS(样式)/JS(逻辑),思路与网页三件套同源,会网页就会小程序;
- 生命周期:注册账号(个人/企业)→ 开发者工具编码 → 真机预览 → 提交审核(1-3 天)→ 发布;
- 与网页的关键差异:包体限制(主包 2MB)、必须 HTTPS 接口且域名要备案登记、支付/登录走微信体系、审核规则要提前读;
- 适用判断:用户在微信里、要支付或社交分享——否则网页更自由。
20. App 开发入门
- 三条路线:原生(iOS Swift/Android Kotlin,性能最强成本最高)/跨平台(Flutter/React Native,一套代码双端)/混合(H5 套壳,最快最弱);
- 新手建议:Flutter 起步;先做网页验证需求再上 App;
- 额外工作:开发者账号(苹果 $99/年)、商店审核、版本强制更新机制、推送服务。
21. AI 辅助开发(这个时代的杠杆)
- 分工:AI 出代码/文档/测试初稿,人类出需求/验收标准/最终判断;
- 关键实践:把验收标准写成测试(AI 的错误会被测试拦住);让 AI 先出方案再写码;给 AI 完整上下文(口径文档直接喂给它);
- 红线:密钥与敏感数据绝不进 AI 对话;AI 产出必须过人工验收;
- 实证:业务系统 全程 AI 结对,十天完成传统团队数周的活——杠杆真实存在,但验收权永远在人。
开发完全手册 · 第 8/11 节 · 约 1 分钟
第七部分 实战复盘:某出口企业业务系统从 0 到 v8
时间线(压缩版):需求(旧工具不符合业务动线)→ 预览方案确认信息架构 → v8 上线(八业务台)→ 实时化(轮询+缓存)→ 门禁(Access)→ 写回闭环(令牌+白名单)→ 经营分析台 → 准实时降频与按需部署 → 单客户透视 → 费用管理工具 → 全代码体检 → 说明页与文档体系。
踩坑清单(每条都是真金白银的教训):
1. 悬浮表头没配滚动容器→表头漂进数据里(布局细节要实测); 2. 生成代码少 6 个闭合标签→后面的 Tab 被吞(结构配平要机器查); 3. 计划任务环境编码不同→脚本一到定时环境就崩(输出强制 UTF-8); 4. 接口路由漏一个 await→永远返回空对象(接口测试必须含路由层); 5. 部署指纹漏了一个文件→改了代码永远不上线(指纹清单要全); 6. Markdown 粗体符号进了 PDF 生成器→字面显示星号(内容管线要统一); 7. 测试桩缺一个属性→假报警(桩要贴近真实); 8. 密钥管道带隐形回车→服务端校验永远失败(两端都做归一化)。
共同规律:每个坑都是"在 A 环境正常、在 B 环境炸"——所以要有贴近真实环境的自动化验收,和敢于上线前的硬闸。
开发完全手册 · 第 9/11 节 · 约 1 分钟
附录 A:学习路径图(小白→大师四阶段)
| 阶段 | 目标 | 学什么 | 检验标准 |
|---|
| 小白(1-2 月) | 看懂并改现有页面 | HTML/CSS 基础、浏览器 F12、读懂 JSON | 能改一个页面的文字颜色并发布 |
| 入门(3-6 月) | 独立做小工具 | JS 编程、API 调用、一个托管平台、Git | 独立上线一个带数据的查询页 |
| 熟练(6-12 月) | 做完整业务系统 | 数据建模、鉴权、测试、部署自动化、安全五件事 | 上线一个多人使用的系统并稳定运行一季 |
| 大师(持续) | 让系统长期可靠演进 | 双实现对账、监控自愈、成本工程、文档沉淀、重构判断 | 系统 3 个月零人工干预仍正确运行;新人靠文档就能接手 |
开发完全手册 · 第 10/11 节 · 约 1 分钟
附录 B:工具与资源清单
- 编辑器:VS Code(免费,插件全);
- 托管:Cloudflare Pages(首选免费)/Vercel/腾讯 EdgeOne(国内,需备案);
- 图表:ECharts(本案例用)/Chart.js;
- 协作:Git+GitHub;飞书多维表格(轻数据库+协作);
- 测试:Node 内置测试/Playwright(界面自动化);
- AI 助手:ZCode/Claude 等(配合测试使用);
- 参考文档:MDN(Web 技术权威文档)/各平台官方文档。
开发完全手册 · 第 11/11 节 · 约 2 分钟
附录 C:上线前检查清单(20 条)
1. 需求四问有书面答案;2. 口径文档已写;3. 数据源唯一;4. 敏感数据三层分层;5. 门禁已启用;6. HTTPS 生效;7. 服务端输入校验;8. 无删除功能或删除有确认;9. 密钥不在源码;10. 错误有降级(页面不空白);11. 移动端可用;12. 表头/布局在真实浏览器实测;13. 关键计算有测试;14. 部署有回滚方案;15. 自动动作有日志;16. 版本更新有提醒机制;17. 临时使用有登出;18. 口径/使用/技术三类文档在位;19. 找一个非开发者试用并反馈;20. 记得上第一版功能清单外的事,排进下一版。
本手册与《某业务系统技术文档》配套:一本讲"这套系统",一本讲"这类系统怎么做"。术语详见《技术说明书》附录 A(30 条)。
系列书目(v1.0,共八种,2026-10-27):《某业务系统技术文档》(系统档案)·《开发完全手册》(交付方法论)·《编程指南》(代码手艺)·《飞书使用指南》(飞书平台)·《ZCode 使用指南》(ZCode 平台)·《WorkBuddy 使用与迁移指南》(旧平台)·《AI Agent 入门指南》(Agent 原理·作者即案例)·《AI Agent 必修课·合编版》(三册课程化重排)。术语详见《技术说明书》附录 A。(本册定位:交付方法论,这类系统怎么做)系统大改后由 Dan 同步更新两册。
编程指南 · 第 1/10 节 · 约 1 分钟
导语
v1.0 ｜ 2026-10-27 ｜ 编制:Dan(AI 助手) ｜ 审定:Forrest
系列第三册,与《开发完全手册》(交付方法论)、《某业务系统技术文档》(系统档案)配套。
系列书目(v1.0,共八种,2026-10-27):《某业务系统技术文档》(系统档案)·《开发完全手册》(交付方法论)·《编程指南》(代码手艺)·《飞书使用指南》(飞书平台)·《ZCode 使用指南》(ZCode 平台)·《WorkBuddy 使用与迁移指南》(旧平台)·《AI Agent 入门指南》(Agent 原理·作者即案例)·《AI Agent 必修课·合编版》(三册课程化重排)。术语详见《技术说明书》附录 A。(本册定位:代码手艺)本册讲编程手艺本身:从第一行代码到工程级编程的完整路径。
全书案例都来自某出口企业业务系统的真实代码与真实事故——包括几个花了真金白银时间才抓到的 bug。学编程最怕教科书式的假例子,这里全是真枪实弹。
编程指南 · 第 2/10 节 · 约 2 分钟
第一部分 起点 · 小白(第一行代码之前)
1. 编程到底是什么
一句话:编程=把想法翻译成机器能一步步执行的指令。
程序的本质永远是同一个模式:
输入 → 处理 → 输出
某出口企业业务系统的每一个功能都是这个模式:输入=飞书里的 数百行原始数据 → 处理=过滤、聚合、算指标 → 输出=你看到的图表和表格。学会编程,就是学会把"处理"这个环节拆成机器能懂的、一条条不含糊的小步骤。
新手最大的心理障碍是"我数学不好/逻辑不行"。其实编程用的数学不超过四则运算,需要的逻辑就是日常讲道理:如果……就……;重复做直到……;把东西分类放好。语言人人都会,难学的只是"说得足够精确"。
2. 选第一门语言
| 语言 | 一句话定位 | 建议 |
|---|
| JavaScript | 浏览器唯一语言,做网页必学 | 想做网页/App,从它开始 |
| Python | 最接近人类语言,数据处理之王 | 想做数据处理/自动化,从它开始 |
| 其他(Java/Go/C…) | 各有擅场 | 第一门别选,第二门再考虑 |
不用纠结,两门都值得学,而且第二门会比第一门快十倍——学编程学的是"翻译的思路",语言只是方言。本手册所有例子同时给 JS 和 Python 双版本(业务系统正好两种都用:页面 JS+构建 Python)。
3. 环境十分钟搭好
1. 编辑器:装 VS Code(免费); 2. 运行:网页代码用浏览器按 F12 的 Console 就能跑;Python 装官网解释器; 3. 第一个程序(仪式感要有):让屏幕打印"你好, Forrest":
// JavaScript —— 浏览器按 F12,粘贴回车
console.log('你好, Forrest');
编程指南 · 第 3/10 节 · 约 2 分钟
Python —— 存成 hello.py,命令行执行 python hello.py
print('你好, Forrest')
跑通了?恭喜,你已经是程序员了——剩下的只是把"打印一句话"换成"打印一万条订单的汇总"。
## 4. 基础四件套:变量 / 条件 / 循环 / 函数
一切程序,无论多复杂,都由这四件套拼出来。用项目真实代码讲:
**变量**——给一个值起名字,以后用名字叫它:
var today = '2026-10-27'; // JS var delay = dday(r.due, today); // delay = 某发票的逾期天数
**条件**——如果…就…,否则…:
if (d < 0) return pill('逾期 ' + (-d) + ' 天', 'red'); // 逾期:红色标签 if (d <= 7) return pill(d + ' 天后到港', 'blu'); // 7 天内到港:蓝色
(业务系统收汇台的真实代码:一个条件决定标签颜色和文字。)
**循环**——对一堆东西逐个处理:
for r in rows: # 对 数百行订单逐行 total += r['美元金额'] # 累加金额
**函数**——把一段常用处理打包起名,以后一行调用:
function fnum(v) { // 函数:把不确定的值安全地变成数字 var n = parseFloat(v); return isNaN(n) ? 0 : n; // 转不成数字就给 0,绝不崩 }
这个 4 行的小函数在业务系统用了几十处——飞书字段里混着文字、空值、数字,全都靠它兜底。**好函数就是给一类麻烦起个名字,以后再也不用操心。**
> **口诀:变量起名字,条件做选择,循环干重复,函数装套路。**
---
编程指南 · 第 4/10 节 · 约 3 分钟
第二部分 入门 · 写出能用的程序
5. 数据结构:东西怎么摆放
- 列表(List/Array):一排同类的格子——业务系统的 数百行订单就是一个大列表;
- 字典/对象(Dict/Object):带标签的格子——每一行订单是
{发票号: 'AD-XXXXXXXX-X', 数量: 50000, …},按标签取值不看位置; - 嵌套:列表里套字典、字典里套列表——真实数据都长这样。
JSON 就是这种结构的文本写法,是系统各端口传数据的通用集装箱。学会 JSON 的读写,你就学会了看懂所有接口。
6. 文本处理:编程一半的活儿
数据清洗、格式转换、规则匹配,本质都是处理文本。三件常备武器:
// 1. 切片:从 '2026-11-03' 取出月份
var month = etd.slice(0, 7); // '2026-11'
// 2. 替换:2026/11/03 ← 2026-11-03
var shown = d.replace('-', '/');
// 3. 正则(文本处理的瑞士军刀):识别日期格式
var isDate = /^\d{4}-\d{2}-\d{2}/.test(v);
正则第一次看像天书,记住三个最常用的就够起步:\d 数字、+ 一个或多个、^…$ 从头到尾完全匹配。剩下的用到再查。
7. 错误与调试:程序员的主业
行业真相:写代码占三成,找错占七成。调试能力才是高手与新手的分水岭。
调试心法四步(业务系统实战全部用过):
1. 读错误信息——它通常直接告诉你哪一文件哪一行、什么性质的错; 2. 缩小范围——在可疑位置前后打印中间值,看哪一步开始不对; 3. 最小复现——把问题剥离到最小例子,排除干扰; 4. 查"两个环境的差异"——最常见的坑:A 环境正常、B 环境炸。
项目真实事故四则(每一则都是上面四步抓到的):
| 事故 | 现象 | 真因 | 教训 |
|---|
| 编码崩溃 | 定时任务里脚本永远失败、输出为空 | 任务环境输出是 GBK,打印"✓"符号即崩 | 脚本开头强制 UTF-8;不同环境行为可能不同 |
| 引号蒸发 | 生成的网页语法错误 | 生成器模板把转义符 \' 吃掉 | 生成类代码要单独做语法校验 |
| 路由漏 await | 费用解锁永远失败,与令牌对错无关 | 异步函数没等它执行完就返回了结果 | 接口测试必须覆盖"路由接线层" |
| 神秘回车符 | 令牌一字不差却校验失败 | 上传管道混入隐形回车符,两端值实际不等 | 两端都做归一化(trim) |
注意共同规律:四个都不是"逻辑写错",而是环境、转义、异步、隐形字符这类"看不见的地方"。见得多你就有了"味道感应"。
8. 版本控制:Git 最小集
只需要五个命令起步:git add .(记下改动)→ git commit -m '说明'(存档)→ git push(上传)→ git log(看历史)→ git checkout .(反悔,撤回未存档改动)。单人项目这一套就够;核心价值:每次改动有存档,任何时间可回退。
编程指南 · 第 5/10 节 · 约 3 分钟
第三部分 熟练 · 写出好程序
9. 代码质量四原则
1. 命名见名知义:未付金额 好过 u2;函数 shipped() 一看就知道"这行是否已开船"; 2. 小函数:一个函数只做一件事,超过一屏就拆; 3. DRY(Don't Repeat Yourself):同样的逻辑写两遍,将来必有一遍忘记改——业务系统把"客户线判定 cgrp"在 Python/JS/页面三处共用同一定义,就是因为吃过不同步的亏; 4. 删除死代码:注释掉的旧代码直接删(版本控制里永远找得回)。业务系统体检时清掉的 sorter() 死函数曾让新人误以为还在使用。
10. 数据加工编程(业务系统的核心手艺)
业务系统最核心的代码模式,值得单独学:
原始行(373 条,字段杂乱) → 归一化(normalize:统一格式/字段名/类型)
→ 干净记录(recs) → 聚合(aggregate:分组算指标) → 图表与表格
要点:
- 归一化:原始数据永远不干净(选项 ID 与文字混排、日期是毫秒时间戳、空值五花八门)——先洗成统一格式,后面所有代码受益;
- 聚合就是分组求和:按月分组→每月的应付/已付/未付;按客户分组→排行;
- 加权平均:∑金额÷∑数量,不是"单价的平均"——均价、吨成本全是这个公式;
- 口径即法律:每个指标的定义写进文档,代码只是文档的实现。
11. 前端编程三件事:DOM / 事件 / 状态
- DOM:页面上的每个元素都是可操作的对象——找到它、改它;
- 事件:点击/输入/定时——"当用户做 X,就执行 Y";
- 状态:程序要记住的东西(当前筛选、编辑模式开关、数据指纹)。前端 bug 九成出在"状态和画面不一致"。
业务系统的热更新就是三件事的组合:每 60 秒拉数据(事件)→ 比对指纹(状态判断)→ 变了才重画(DOM 操作)。
12. 异步编程:最容易踩的坑
有些操作需要等待(网络请求、读文件),程序不能傻等,于是有了"异步"。JS 的演进:回调函数 → Promise → async/await(现在的标准写法,最像普通思维)。
血泪案例:费用解锁接口上线时,路由写 const out = handleFee(...) 漏了 await——异步函数立刻返回一个"还没完成的承诺对象",把它直接转成 JSON 就成了 {}。结果:无论用户输什么令牌,永远返回 403 空对象。排查三轮才发现,修复=加一个单词。
教训:凡是调用异步函数,必须 await;凡是没有 await 的异步调用,拿到的是"空头支票"。审代码时第一眼就看这个。
13. 正则表达式(进阶但值得)
文本处理的终极武器,一个模式顶二十行 if。项目真实用例:从 mixed 字段里识别"2019/2020"年份、把全角字符归一成半角、校验"YYYY-MM-DD"日期格式。学习策略:先会三个符号,其余用到再查,一周就上手。
编程指南 · 第 6/10 节 · 约 2 分钟
第四部分 高手 · 工程化
14. 测试:让机器替你操心
人肉点一遍不算测试——你总会漏。测试=把"怎么算对"写成机器能执行的检查,每次改动自动重跑。业务系统的三层测试:
| 层 | 测什么 | 案例 |
|---|
| 等价性测试 | 两套实现算同一数据,结果必须逐字段一致 | JS 接口 vs Python 构建,×××比对 |
| 场景测试 | 合法/错误令牌/越权字段/非法值 | 写回接口四连测,错的一律拒绝 |
| 无头渲染测试 | 装进无界面浏览器,遍历全部页面×年份×基准 | 任何渲染报错当场暴露 |
测试的隐藏价值:它逼你把"怎么算对"想清楚——很多 bug 在写测试时就被自己发现了。
15. 调试进阶:三步锁定法
以"费用令牌永远无效"事故为例(排查三轮的真案):
1. 加诊断输出:服务端拒绝时返回两个长度(你输入的长度/服务器存的长度)——不泄露内容,只给数字; 2. 读数字定位:用户报回"undefined/undefined"→响应体是空对象→说明根本不是令牌校验失败,是路由层返回了空——范围从"令牌问题"缩小到"路由问题"; 3. 最小复现验证:本地直接调函数(通过)→ 说明问题在函数与网络之间的"接线层"→ 检查路由 → 抓到漏 await。
二分思维:在"正常"和"不正常"之间不断取中点打印,三五行就能锁定问题边界。
16. 编码规范与自动化审查
规范的意义不是美,是防止低级错误。两招落地:①团队定一份简短规范(命名/缩进/注释何时写);②能用机器查的绝不靠人眼——语法检查、结构配平检查,全部做成部署硬闸(业务系统三道闸多次实战拦下坏版本)。
17. 性能思维:先测量,后优化
没有测量就优化=瞎猜。流程:①发现慢→②用工具量"慢在哪"(浏览器 F12 性能面板)→③只优化占比最大的那一块。项目实例:页面 1.3MB,量化后发现 90% 是图表库——优化方向立刻清晰(按需打包),而不是到处乱抠。通用武器只有四招:少传输(压缩)、少计算(缓存)、晚执行(懒加载)、批处理(合并请求)。
编程指南 · 第 7/10 节 · 约 2 分钟
第五部分 大师 · 思维
18. 抽象与命名:大师的分水岭
初级程序员写"让机器跑起来"的代码;高级程序员写"让人改起来放心"的代码。判断标准就一条:半年后的自己(或接手的人)能不能五分钟看懂并安全修改。
- 好抽象:业务系统的
cgrp()(客户并组)——口径变一次,三处实现同步改一行; - 坏抽象:把十种逻辑塞进一个函数,改任何一处都要通读全函数;
- 命名的终极测试:读出声。"shipped""未付总盘"天然自解释;"flag1""tmp"是罪犯。
19. 防御式编程:假设一切输入是坏的
服务端三大假设:用户会输错、会越权、会故意使坏。所以:字段白名单(只接受列出的)、值域校验(枚举/格式/范围)、两端归一化(空白/全角)、错误信息不泄露内部细节。业务系统的编辑接口对"错令牌/越权字段/非法选项"三连攻击全部拒绝——这不是功能,是底线。
另一面是对自己的防御:结构配平检查、语法硬闸、指纹比对——假设"自己一定会犯错",用机器在门口拦。事实证明它拦的都是真错误。
20. AI 时代的编程:角色升级,不是淘汰
AI 能写代码,但三件事永远在你手里:
1. 定义问题:AI 不知道你的业务口径("出货"和"成交"的区别); 2. 验收标准:把"怎么算对"写成测试——AI 一本正经写错时,测试会拦住它(业务系统开发中被测试拦下的错误不下十次); 3. 最终判断:架构选择、敏感数据边界、要不要上线——责任无法外包。
实操建议:把口径文档、已有代码喂给 AI 当上下文;小步快跑(每步都验证);把它当"打字飞快但需要复核的初级同事"。
21. 持续学习:大师也没有毕业
编程的半衰期短,但底层不变:HTTP、数据库、加密、操作系统这些学了二十年不过时。策略:框架跟官方文档走马观花即可,底層原理深耕;每做一个新项目,强制自己学一项新东西(业务系统项目里现学的是 Cloudflare Workers 和飞书 API);读别人的好代码(开源项目)是进步最快的方式。
编程指南 · 第 8/10 节 · 约 1 分钟
附录 A:常见错误速查表(真实事故版)
| # | 报错/现象 | 常见原因 | 修法 |
|---|
| 1 | xxx is not defined | 名字拼错/未定义/作用域不对 | 检查拼写与声明位置 |
| 2 | Cannot read properties of undefined | 从空值里取属性 | 取之前先判空(v && v.length) |
| 3 | Unexpected token 语法错 | 括号/引号不配对 | 数括号;用编辑器高亮 |
| 4 | 页面正常脚本崩 | 语法错误导致整段解析失败 | node --check 之类的工具查 |
| 5 | 中文/符号打印报 UnicodeEncodeError | 输出环境编码是 GBK | 脚本开头强制 UTF-8 |
| 6 | 值一字不差却不相等 | 隐形字符(回车/全角/空格) | 两端 trim+归一化 |
| 7 | 接口永远返回空对象 | 调异步函数漏 await | 补 await |
| 8 | 改了代码线上没反应 | 忘部署/部署指纹没覆盖该文件/浏览器缓存 | 指纹清单补全;强刷;版本横幅 |
| 9 | 定时任务正常手动跑崩 | 环境差异(编码/变量/路径) | 在任务环境里复现并打日志 |
| 10 | 表格/布局错位 | HTML 标签不配平/样式覆盖 | 配平检查;逐层排查样式 |
编程指南 · 第 9/10 节 · 约 1 分钟
附录 B:练习清单(全部可在业务系统代码上做)
1. 【小白】跑通第一个"你好"程序(JS 与 Python 各一次); 2. 【小白】写函数 fmt(n):把 1234567 变成 "1,234,567"; 3. 【入门】读 data.json,统计每个"订单状态"各有多少行; 4. 【入门】给跟单台加一列"账期天数"(字段 ac),会改表头与行两处; 5. 【入门】写正则:从发票号 AD-XXXXXXXX-X 提取年份与序号; 6. 【熟练】给费用明细加"按客户筛选"下拉(参考现有按月筛选); 7. 【熟练】复制等价性测试框架,给一个新的聚合指标做对账; 8. 【熟练】用无头测试跑一遍全部 Tab,并给某个函数补上诊断日志; 9. 【高手】把月度费用聚合从 JS 移植成 Python 版并做等价性测试(体会双实现对账); 10. 【高手】做一次完整部署(改一行页面文案→硬闸→上线→横幅出现→刷新)。
编程指南 · 第 10/10 节 · 约 1 分钟
附录 C:学习资源
- JavaScript:MDN(Web 技术权威文档,中英文全)·《JavaScript 高级程序设计》(红宝书);
- Python:官方教程(中文)·《Python 编程:从入门到实践》;
- 练手:LeetCode(算法)/自由改业务系统代码(最真实);
- 查询:正则用 regex101.com 边写边试;报错直接整句搜索(99% 有人踩过)。
系列书目:《某业务系统技术文档》(系统档案)·《开发完全手册》(交付方法论)· 本册(编程手艺)。三册配套,术语互见。
ZCode 使用指南 · 第 1/7 节 · 约 1 分钟
导语
v1.0 ｜ 2026-10-27 ｜ 编制:Dan(AI 助手) ｜ 审定:Forrest
系列第五册。
系列书目(v1.0,共八种,2026-10-27):《某业务系统技术文档》(系统档案)·《开发完全手册》(交付方法论)·《编程指南》(代码手艺)·《飞书使用指南》(飞书平台)·《ZCode 使用指南》(ZCode 平台)·《WorkBuddy 使用与迁移指南》(旧平台)·《AI Agent 入门指南》(Agent 原理·作者即案例)·《AI Agent 必修课·合编版》(三册课程化重排)。术语详见《技术说明书》附录 A。(本册定位:生产工具(ZCode)用法)前三册讲产出(系统/交付/代码/平台),本册讲生产工具本身——ZCode,AI 编程代理。全部案例来自某出口企业业务系统项目:这个十天建成、持续迭代的系统,就是用 ZCode 做出来的。
一句话定位:ZCode 不只是"会聊天的 AI",而是能动手的 AI 同事——它可以直接读写你电脑上的文件、执行命令、操作浏览器、定时干活,并把每一步给你看。
ZCode 使用指南 · 第 2/7 节 · 约 2 分钟
第一部分 起点 · 小白
1. ZCode 是什么
传统 AI 聊天:你问,它答,答案你自己复制粘贴。ZCode 的区别:它有手。
| 能力 | 聊天 AI | ZCode |
|---|
| 回答问题/写方案 | ✓ | ✓ |
| 生成代码 | 只给文本 | 直接写入你的项目文件 |
| 执行命令 | ✗ | 直接运行并看到结果(构建/测试/部署) |
| 上网查资料 | ✗/有限 | 真浏览器打开网页验证 |
| 定时干活 | ✗ | 可注册定时任务(每天自动推数据) |
| 记住项目规矩 | 每次重复交代 | 工作区规则文件自动加载 |
一句话:聊天 AI 是顾问,ZCode 是驻场工程师——你出需求与验收,它动手并汇报。
2. 第一次使用:怎么"下需求"
对 ZCode 说话不需要命令语法,说人话即可。好需求的四要素(与《开发完全手册》的需求四问同源):
1. 给谁/干什么:"给订单数据做一个网页看板,手机能看"; 2. 数据在哪:"数据在飞书多维表格里"; 3. 验收标准:"飞书改了数据,网页要能自动变"; 4. 边界:"费用相关的先不做"。
反面教材:"帮我做个网站"——太泛,来回追问浪费时间。正面教材:业务系统立项时那句"数据散在飞书和 Excel 里,查个数要翻三个地方,做个能自动更新的看板"——一句话含了用户、痛点、数据源、验收方向。
3. 会话与上下文
- 一个会话=一个工作现场:ZCode 会记住本会话里说过的一切;跨会话的记忆靠工作区文件(见第五章);
- 上下文会满:超长会话会被自动压缩,细节可能丢失——所以重要规则要落进文件(规则文件/文档),不能只活在对话里;
- 并行会话:可以同时开多个会话分头干活,但同一份文件别让两个会话同时改(会互相覆盖,我们踩过);
- 会话有备份:每日定时把会话库快照+导出存档(可配置),换电脑/丢数据有底。
4. 首次协作的正确姿势
不要一上来就让它"自由发挥"。推荐开场三句话:"这是我的工作区(指给它看)"、"这是规则文件(如有)"、"这是第一个任务+验收标准"。ZCode 会自己读目录、读文件、提出方案——你只需要像对实习生一样:给清楚任务,验收它交回来的东西。
ZCode 使用指南 · 第 3/7 节 · 约 2 分钟
第二部分 入门 · 日常使用
5. 六类日常指令形态(按目的分)
| 你想要 | 怎么说 | ZCode 做什么 |
|---|
| 查 | "订单表里 VIP 有几行没付款" | 读文件/API/数据库,给出答案与出处 |
| 改 | "把横幅字体调大,颜色改红色,醒目一点" | 定位代码→修改→自检→交付 |
| 建 | "做一个费用管理页,要有图表和筛选" | 设计→编码→测试→上线一条龙 |
| 自动化 | "每天早上 9 点把订单重点推到飞书群" | 注册定时任务+写推送脚本 |
| 排障 | "网页数据停在上午 8 点了,是不是出问题了" | 分层定位(线上/本地/任务/网络)→修复→回归 |
| 沉淀 | "把今天的工作整理成文档" | 汇总日志→成文→登记索引 |
6. 工作区与规则文件:让 AI 记住你的规矩
ZCode 支持在工作区放一个指令文件(如 AGENTS.md),每次会话自动加载——相当于新同事入职必读的员工手册。业务系统的规则文件包含:身份约定(称呼)、入会必做(核对日期/读记忆/读邮件简报)、交付纪律(邮件只拟不发/外部文件先备份)、铁律(禁删数据/逐任务记日志)。
经验:规则文件是"越用越厚"的——每次被纠正就沉淀一条。它是 AI 协作里回报率最高的投资:写一次,永久生效,跨会话跨天都不用再教。
记忆文件:除规则外,还有持久记忆(项目要点/待办快照/协作风格),供跨会话恢复上下文。原则:重要的进文件,临时的留对话。
7. 逐任务日志:AI 工作的台账
业务系统铁律:每完成一项实质工作,立即在当日日志追加一条(带时间戳)。价值:①跨会话接手有据可查;②"这个改动谁在什么时候做的"永远可追溯;③审计时是证据链。建议所有长期项目都立此规矩,并要求 AI 遵守。
ZCode 使用指南 · 第 4/7 节 · 约 2 分钟
第三部分 熟练 · 能力面与防护
8. 能力面:ZCode 的"手"能伸多长
| 能力 | 典型用法(项目实例) |
|---|
| 文件读写 | 读写项目文件、生成报告/文档/网页 |
| 命令执行 | 构建脚本、部署、语法检查、文件整理 |
| 浏览器自动化 | 打开网页实测交互、截图、抓取渲染结果 |
| 文档生成 | PDF(ReportLab 排版)/DOCX/XLSX/PPT |
| 可视化 | 会话内交互式图表/流程图/方案预览 |
| 定时任务 | 每小时看板刷新、每日推送/简报/备份 |
| 子代理 | 把独立子任务(如全库搜索)派给并行助手 |
| 数据/API | 调飞书/调任何有接口的服务 |
9. 防护机制:让"能干"变成"放心地干"
ZCode 的权限体系分多层,建议都启用:
1. 权限模式:每类操作可设为"自动放行"或"逐条确认"(读文件自动、发邮件必确认之类); 2. 钩子(Hook):在特定动作上挂检查器——业务系统的钩子会拦截含危险字符的命令、对覆盖已有文件的写入提出警告、在写文档时自动注入当前系统时间(防止时间戳手误); 3. 部署硬闸:自动化管线里的质量门(语法/结构检查),坏版本上不了线; 4. 审计留痕:敏感操作自动记录(谁/何时/改了什么)。
设计哲学:不是限制 AI,而是把"容易犯的错"固化成机器检查——人只审"该不该做",机器审"格式对不对"。上线以来,硬闸实际拦下的坏版本全部是真错误。
10. 验收:人类的不可让渡职责
AI 产出必须验收,三个层次:
- 机器验收(全自动):语法检查/测试/对账——写好一次,终身受益;
- 抽查验收(半自动):关键数字与独立计算的基准比对(业务系统惯例:每个新指标上线前用另一套脚本独立算一遍);
- 人眼验收(必须):界面好不好用、口径符不符合业务实际——这是委托方不可让渡的判断。
ZCode 使用指南 · 第 5/7 节 · 约 1 分钟
第四部分 高阶 · 自动化与协同
11. 定时自动化:让系统自己转
ZCode 可注册定时任务(自动化),把"每天/每小时要做的事"固化。业务系统现役六条自动化:每日 9:00 订单重点推飞书群、每小时看板兜底刷新、每日 18:30 邮件维护、18:35 邮件简报、每日两次会话备份。设计三原则:
1. 幂等:同一任务跑两遍结果一样(撞车不出错); 2. 留痕:每次运行(含跳过)记日志; 3. 自愈:失败不影响线上旧数据,下一轮自动纠正。
12. 子代理与并行
大任务可拆给子代理并行干(如"全库搜索汇总""多方案比较"),主会话只收结论。适用:独立、可并行的调研型子任务;不适用:强顺序依赖的改造。经验:并行三路子代理做资料汇总,比串行快一倍以上。
13. 多 AI 协作的节奏
- 让 AI 提方案,你选方案:同一需求要 2-3 版设计预览再定稿(业务系统改版时做过交互预览,避免了一次返工);
- 让 AI 互查:一个 AI 写、测试与硬闸把关,比"自己写自己查"可靠;
- 人的精力花在刀刃上:口径定义、验收标准、界面审美——这些 AI 替代不了的判断。
ZCode 使用指南 · 第 6/7 节 · 约 1 分钟
第五部分 大师 · 心法
14. 提问的质量决定产出的质量
同一需求的两种问法:"改一下那个页面"vs"费用台的解锁按钮点了没反应,预期是弹令牌输入框"——后者自带位置+现象+预期,第一轮就能命中。积累自己的需求模板:位置(哪/哪里)+现象(现在怎样)+预期(应该怎样)。
15. 什么该自动化,什么不该
该自动化的:重复、有明确对错、结果可校验的(部署/对账/备份/推送); 不该自动化的:对外发送、删除、金额调整、口径变更——这类保留"人工确认"闸(业务系统红线:发信逐封确认、记录禁删、金额条款走会话)。 判断口诀:错了能自动发现且能自动回滚的,自动化;错了发现不了或回不了头的,留给人。
16. 信任建立:小步快跑 + 可回退
对 AI 的信任不是靠话术建立的,是靠机制:小步交付(每次改动可见可验)、自动测试(对错机器判)、一键回退(坏了随时退)。业务系统从"第一天"就建立这套机制,到后期 AI 自主完成整 Tab 开发+部署,人只做验收——这个信任曲线是可以复制的。
ZCode 使用指南 · 第 7/7 节 · 约 1 分钟
第六部分 FAQ
| 问题 | 答案 |
|---|
| 不会编程能用 ZCode 吗 | 能——业务系统的委托方不写代码,靠"说清需求+验收结果"驱动;但学一点基础(见《编程指南》)能显著提升沟通精度 |
| AI 会不会乱改我的文件 | 有权限模式与钩子把关;重要文件改前有警告与备份机制;仍建议重要项目做会话/文件备份 |
| 数据安全吗 | 传输与本地处理;密钥类绝不贴进对话(进对话=进本机会话库);敏感操作走确认闸 |
| 为什么有时 AI 忘了之前说的 | 会话上下文有限——重要规矩进规则文件与记忆文件,别依赖对话记忆 |
| 一个会话能干多久 | 长会话会自动压缩上下文;大项目建议按主题分会话+靠文件传递状态 |
| 怎么让 AI 记住我的偏好 | 第一次被纠正时说"以后都这样"——并确认它写进了规则文件 |
| 自动化任务坏了怎么办 | 查运行日志→手动跑一次看报错→修→强制触发验证;设计良好的任务失败不影响线上 |
| AI 写的代码质量行吗 | 用测试与硬闸兜底(见第十章)——质量靠机制,不靠祈祷 |
系列书目:《技术说明书》(系统档案)·《开发完全手册》(交付方法论)·《编程指南》(代码手艺)·《飞书使用指南》(平台用法)· 本册(生产工具)。术语详见《技术说明书》附录 A。
飞书使用指南 · 第 1/15 节 · 约 1 分钟
导语
v1.0 ｜ 2026-10-27 ｜ 编制:Dan(AI 助手) ｜ 审定:Forrest
系列第四册。前四段案例全部来自某出口企业业务系统的真实飞书用法:订单 Base(14 表·跟踪表 70 字段)、高级权限四角色、自建应用、lark CLI 日常与排障——书上每一条都真实跑过。
配套:《技术说明书》(系统)·《开发完全手册》(交付)·《编程指南》(代码)· 本册(飞书平台)。
系列书目(v1.0,共八种,2026-10-27):《某业务系统技术文档》(系统档案)·《开发完全手册》(交付方法论)·《编程指南》(代码手艺)·《飞书使用指南》(飞书平台)·《ZCode 使用指南》(ZCode 平台)·《WorkBuddy 使用与迁移指南》(旧平台)·《AI Agent 入门指南》(Agent 原理·作者即案例)·《AI Agent 必修课·合编版》(三册课程化重排)。术语详见《技术说明书》附录 A。(本册定位:飞书平台用法)
飞书使用指南 · 第 2/15 节 · 约 3 分钟
第一部分 起点 · 小白
1. 飞书能干什么(全景)
飞书不只是聊天工具,它是一个套件:即时消息、云文档、多维表格(超级 Excel)、邮箱、日历、审批、视频会议,以及最容易被忽视的开放平台——让外部程序读写飞书数据的入口。本册重点讲两块最出活儿的:多维表格(数据中枢)和 lark CLI(自动化入口),外加把它们连起来的开放平台。
我们的真实用法一览:订单全生命周期管在多维表格(14 张表);业务系统看板实时读它;自动脚本每天对账回填它;AI 助手用它查邮件/发消息/写记录。
2. 多维表格入门:不只是 Excel
| 概念 | 是什么 | 项目实例 |
|---|
| Base(多维表格) | 一个数据文件,内含多张表 | 订单 Base(14 张表) |
| 数据表 | 一张二维表 | 跟踪表(主账)/合同表/产品表/报关单明细… |
| 行(记录) | 一个事实 | 一行=一个出运批次(一票可拆多行) |
| 字段(列) | 有类型的列 | 文本/数字/日期/单选/复选/公式/Lookup… |
| 视图 | 同一数据的不同看法 | 按客户筛、按月看、看板视图 |
| 公式 | 自动计算的列 | 美元金额=数量×price |
| Lookup | 从关联表自动带数据 | 跟踪表的客户/国家从合同表自动带出 |
与 Excel 的本质区别:Excel 是"一张自由画布",多维表格是"类型化的小数据库"——每列有类型、行间可关联、可配权限、可被程序读写。用它的正确姿势是按数据库的思维:一表一义、一行一义、字段定类型。
新手三件事:①建表定字段(类型选对);②学会切换视图(同一数据,发货视图/收款视图/单证视图);③把重复动作交给"自动化"(见第八章)。
3. 字段类型:选对类型,事半功倍
业务系统跟踪表 70 个字段的类型选型经验:
| 类型 | 用法 | 坑 |
|---|
| 文本 | 编号/名称/备注 | 免疫力最强,啥都能存(但别拿它存该有类型的值) |
| 数字 | 数量/金额/汇率 | 公式引用它的前提 |
| 日期 | ETD/ETA/付款日期 | 程序读出来是毫秒时间戳,要转本地日期 |
| 单选 | 订单状态/PSS状态 | 选项先建好;程序读时可能回选项 ID 而非文字 |
| 复选框 | 付海运/付陆运/船运文件 | 只有真假两态,勾选即留痕 |
| 公式 | 自动计算列 | 人工不可改;程序读到的是算好的值 |
| Lookup | 跨表带数据 | 值来自目标字段;程序读取有特殊行为(见第六章) |
| 关联 | 连接另一张表的行 | 双向关联=两边自动互见 |
口诀:类型即法律。 数量存文本、日期存文字,后面所有公式和程序都要额外绕路。
飞书使用指南 · 第 3/15 节 · 约 2 分钟
第二部分 进阶 · 让表格自己干活
4. 公式:表格的自动化核心
业务系统跟踪表真实公式(直接可抄):
| 公式列 | 表达式 | 说明 |
|---|
| 美元金额 | = [数量]×[price] | 行级金额 |
| 海运港杂 | = [汇率]×[海运费]+[港杂费]+[其他] | 人民币口径的港杂合计 |
| 总费用 | = [海运港杂]+[陆运费] | 全部费用 |
| 付款到期计算 | = [ETD]+[账期] | 自动算到期日 |
| 毛重 | = [数量]+20×[托盘数] | 托盘每个 20kg |
| 年度 | = MID([发票号],4,4) | 从 AD-XXXXXXXX-X 提取 2026 |
| 吨数 | = [数量]/1000 | |
公式要点:①引用字段用方括号;②公式列人工不可改(数据只录最小集,算的交给表);③注意 Lookup 字段套公式时行为有特殊之处;④公式改动影响下游,改前先看哪些列引用了它。
5. 关联与 Lookup:多表协作
一张表装不下一个业务。业务系统的关系网:合同 ─发货计划─ 跟踪表 ─报关单─ 报关单明细,产品/客户/货代/付款方式都是独立维表。
- 关联字段:在 A 表选 B 表的行(如跟踪表.相关订单 → 合同行);
- Lookup 字段:把关联行的字段值"带过来"显示(如客户名从合同表带出);
- 双向关联:两边都自动显示对方。
两条实战纪律:①人工只录最小集(客户/单价/国家都从合同带出,不重复录);②知道哪些列是算出来的——业务系统的"汇率"列刻意不录在跟踪表(只录在报关单明细),避免两处口径打架。
6. 高级权限:精细到每张表
开高级权限后,协作者必须挂角色才能碰数据(只加协作者不挂角色=依然无权,这是新手最大困惑,也是我们排障三关的最后一关)。
业务系统订单 Base 的角色设计:Reader(只读)/ 跟单(业务操作)/ Editor(全表管理,含跟踪表 manage)/ 普通用户。外部程序(自建应用)同样要挂角色——应用有 API 权限 ≠ 有数据权限,两道门都要过。
角色维护入口:表 → 右上菜单 → 高级权限 → 角色。改完角色让受影响方立刻重试验证。
飞书使用指南 · 第 4/15 节 · 约 1 分钟
第三部分 lark CLI · 自动化的瑞士军刀(重点)
7. CLI 是什么,为什么学它
lark CLI 是飞书的命令行工具:把网页里点来点去的操作变成一条条可脚本化的命令。三大价值:①批量(一次改 100 行);②自动化(接计划任务定时跑);③可留痕可回放(命令历史就是操作记录)。
安装后第一次 lark-cli auth login 走设备授权(扫二维码),之后 lark-cli auth status 查看身份。支持双身份:user(以你个人的权限,最全)与 bot(以应用机器人身份)。
8. 日常高频命令(业务系统实战版)
飞书使用指南 · 第 5/15 节 · 约 1 分钟
列出一张表的所有字段(名称/类型/选项)
lark-cli base +field-list --base-token <BT> --table-id <TID> --format json
飞书使用指南 · 第 6/15 节 · 约 1 分钟
分页读记录(200/页,翻页取全)
lark-cli base +record-list --base-token <BT> --table-id <TID> \ --page-size 200 --offset 0 --format json
飞书使用指南 · 第 7/15 节 · 约 1 分钟
读写记录
lark-cli base +record-create ... # 建行 lark-cli base +record-update ... # 改行
飞书使用指南 · 第 8/15 节 · 约 1 分钟
高级权限诊断(查角色/看角色配置)
lark-cli base +role-list --base-token <BT> lark-cli base +role-get --base-token <BT> --role-id rolXXXX
飞书使用指南 · 第 9/15 节 · 约 3 分钟
任意飞书 API 的"逃生舱"(没有现成命令时)
lark-cli api GET /open-apis/bitable/v1/apps/<BT>/tables --params '{"page_size":50}' lark-cli api POST /open-apis/... --data '{"...":...}'
**实用技巧**:①几乎所有命令都支持 `--format json` + `--jq '表达式'` 直接过滤输出;②高危命令(改权限/删字段)有 `--dry-run` 预览和 `--yes` 确认两级保护;③`+短命令` 优先用,没有再走 `api` 逃生舱;④**API 路径里不能带查询参数**,必须拆到 `--params`,否则报"invalid_argument"。
## 9. 真实排障案例三则(学调试思路)
**案例一:改了权限还不生效。** 现象:后台开了 bitable:app,程序仍报缺权限。原因:自建应用权限要**发版本并审核通过**才生效。教训:权限三件套=开权限→发版本→(数据侧)加协作者/挂角色,缺一不可。
**案例二:RolePermNotAllow。** 现象:API 权限有了、应用也加了协作者,还是拒。诊断:用 CLI `+role-list` 一查——这张 Base 开着**高级权限**,协作者必须再挂进角色。把应用挂到 Editor 角色后立通。教训:高级权限 Base 是"三道门"(API scope→文档协作者→高级权限角色)。
**案例三:CLI 静默无输出。** 现象:命令 rc=49 什么都不打。处理:别死磕,换等价路径(直接 OpenAPI 或另装工具),并把"静默失败"记进心里——**自动化里每一步都要有输出校验**,空输出当失败处理。
## 10. 程序直连:开放平台与自建应用
CLI 之外,程序级对接走自建应用:
创建应用(获取 app_id/app_secret) → 开通权限(scope,如 bitable:app)→ 发版本审核 → 应用加为文档协作者 → (高级权限 Base)挂进角色 → 程序用 app_id+secret 换 tenant_access_token → 调 API
**程序读取的三个真实坑**(业务系统踩过):
1. **单选字段混回**:有的行回文字、有的回选项 ID(opt 开头)——用字段元数据建"ID→名称"映射统一换算;
2. **Lookup 字段回选项 ID**:要去字段的 `filter_info.target_table` 找到目标表的目标字段,把那边的选项表搬过来映射;
3. **日期是毫秒时间戳**:加 8 小时转北京时间再取日期。
**安全三条**:Secret 存本机受保护文件或云端 Secrets,绝不进源码与聊天记录;权限最小化(只开 bitable:app 而非全量);定期可重置密钥。
---
飞书使用指南 · 第 10/15 节 · 约 2 分钟
第四部分 高级功能
11. 多维表格自动化
表格内置"自动化流程":满足条件时自动执行动作(改字段/发消息/调接口)。业务系统用法方向:状态变更自动通知、到期自动提醒。注意:自动化跑在飞书云端,免费版有运行次数限制;复杂逻辑仍建议外部脚本(CLI/程序)——规则简单交给表格自动化,规则复杂交给代码。
12. 仪表盘与视图
多维表格自带仪表盘(图表块:柱/线/饼/指标卡)——轻量统计不用出表。局限:口径自由度不如自建网页(我们业务系统最终自建,但仪表盘适合快速内部看数)。视图家族:表格/看板/画册/甘特/表单——表单视图特别适合"让别人帮你录数据"(客户报订单、内勤录费用)。
13. 邮件与文档集成
飞书邮箱可被 API 读写(业务系统的邮件简报、正文缓存、全文检索都建立在它上面);云文档可程序化创建与更新(周报/台账自动化)。思路:把重复的"读-算-发"流水线脚本化,人只做判断。
14. 集成案例:业务系统的飞书生态用法(全景)
| 用法 | 通道 | 说明 |
|---|
| 看板实时数据 | 自建应用 API | Worker 每次请求实拉 数百行(30 秒缓存) |
| 每小时兜底 | lark-cli(用户身份) | 全量重建快照,指纹比对按需部署 |
| 网页写回 | 自建应用 API | 白名单字段服务端校验后写入 |
| 每日邮件简报 | 邮箱 API | 分类/实体抽取自动生成 |
| 群推送 | 消息 API | 每日 9:00 订单重点 |
| 会话备份 | 本地脚本 | 密钥脱敏后入工作区 |
飞书使用指南 · 第 11/15 节 · 约 1 分钟
第五部分 大师 · 最佳实践与红线
15. 数据治理五原则(项目实证)
1. 唯一事实源:每类数据只在一处维护,他处皆为视图; 2. 禁删原则:有数据的行永不物理删除,只标停用(误判的"重复行"可能是真实批次); 3. 口径文档化:每个公式列、每个指标的分子分母写进口径文档并与实现同步; 4. 最小权限:人按角色、程序按 scope,用不到的权限不开; 5. 变更走流程:口径/结构变更=先改文档→改实现→跑对账→再上线。
16. 安全红线
密钥(App Secret/令牌)不进源码、不进聊天、不进文档——泄露即重置;对外发数据前核敏感分层(哪些字段可以出门);程序身份与个人身份分开审计(业务系统:CLI=个人身份留痕,网页=应用身份+web编辑日志)。
17. 排障通用心法
飞书问题的排障树:①是权限哪一层?(API scope/文档协作者/高级权限角色)②是字段形态?(选项 ID/时间戳/公式值)③是版本没发布?④是限流或静默失败?——每一层都有对应的验证命令(本章都有)。把排障过程写成文档,下次同类问题五分钟解决。
飞书使用指南 · 第 12/15 节 · 约 1 分钟
附录 A:lark CLI 常用命令速查
| 命令 | 用途 |
|---|
lark-cli auth login / status | 设备授权 / 查看身份与令牌有效期 |
base +field-list --base-token BT --table-id TID | 列字段(名称/类型/选项) |
base +record-list --base-token BT --table-id TID --page-size N --offset M | 分页读记录 |
base +record-create / +record-update | 建/改记录 |
base +role-list / +role-get / +role-update | 高级权限角色管理 |
base +dashboard-* | 仪表盘块管理 |
base +view-* / base +form-* | 视图与表单 |
api GET/POST <path> --params '{}' --data '{}' | 任意 OpenAPI 逃生舱(路径不带查询串) |
--format json --jq '<表达式>' | 输出过滤 |
--dry-run / --yes | 预览 / 高危确认 |
飞书使用指南 · 第 13/15 节 · 约 1 分钟
附录 B:字段类型 × API 行为对照(踩坑精华)
| 字段类型 | 页面显示 | API 返回 | 处理 |
|---|
| 文本 | 文字 | 字符串或 [{text}] 数组 | 统一取 text |
| 数字 | 数值 | 数值或字符串 | 强转数字+兜底 0 |
| 日期 | 日期 | 毫秒时间戳 | +8h 转北京日期 |
| 单选 | 文字 | 选项 ID 或文字(混) | 元数据映射统一 |
| 复选 | ✓/空 | true/false/null | 布尔三态处理 |
| Lookup | 文字 | 选项 ID 或值 | 经 filter_info.target_table 取目标表选项映射 |
| 公式 | 计算值 | 计算结果(可能字符串) | 按需强转 |
| 关联 | 行链接 | [{record_ids:[…]}] 等形态 | 取 record_ids[0] |
飞书使用指南 · 第 14/15 节 · 约 1 分钟
附录 C:常见错误与排障
| 错误/现象 | 含义 | 解法 |
|---|
| 99991672 Access denied(scope) | 应用没开该 API 权限 | 开 scope+发版本 |
| RolePermNotAllow | 文档协作者或高级权限角色未配 | 加协作者/挂角色 |
| invalid_argument(path query) | CLI 路径带了查询串 | 拆到 --params |
| 125404 Not Found | 表/字段/视图 ID 不对 | 先 field-list/table 列表核对 |
| 空响应/静默失败 | CLI 偶发或网络 | 换等价命令重试;输出校验当失败处理 |
| 权限改了没生效 | 没发版本 | 版本管理与发布→创建版本→审核通过 |
飞书使用指南 · 第 15/15 节 · 约 1 分钟
附录 D:学习资源
- 飞书开放平台文档(open.feishu.cn/docs)——API 与事件权威来源;
- 多维表格帮助中心——字段/视图/自动化;
- lark-cli --help 与各域手册(base/mail/im/docs 均有分册);
- 本系列:《开发完全手册》(怎么交付)·《编程指南》(怎么写代码)·《技术说明书》(业务系统系统档案)。
WorkBuddy 使用与迁移指南 · 第 1/10 节 · 约 1 分钟
导语
v1.0 ｜ 2026-10-27 ｜ 编制:Dan(AI 助手) ｜ 审定:Forrest
系列第六册·平台篇第二册。诚实定位:WorkBuddy 是某出口企业业务系统早期使用的 AI 助手平台,2026 年 9 月起工作主线已迁移至 ZCode;但至今仍有活的依赖(全套构建/刷新脚本调用的 lark-cli 就装在它的目录里)。因此本册=「还能怎么用 + 现状盘点 + 安全迁移手册」,并附诚实的边界说明:本册基于本项目工作区实证,产品全貌以官方文档为准。
系列书目(v1.0,共八种,2026-10-27):《某业务系统技术文档》(系统档案)·《开发完全手册》(交付方法论)·《编程指南》(代码手艺)·《飞书使用指南》(飞书平台)·《ZCode 使用指南》(ZCode 平台)·《WorkBuddy 使用与迁移指南》(旧平台)·《AI Agent 入门指南》(Agent 原理·作者即案例)·《AI Agent 必修课·合编版》(三册课程化重排)。术语详见《技术说明书》附录 A。(本册定位:旧平台使用与迁移)
WorkBuddy 使用与迁移指南 · 第 2/10 节 · 约 1 分钟
第一部分 起点 · 认识 WorkBuddy
1. WorkBuddy 是什么
WorkBuddy 与 ZCode 同属一类:AI 助手平台——一个能读写文件、执行命令、连接外部服务(飞书等)的智能工作台。它有三样典型资产:
- 技能(Skills):教 AI 做特定任务的说明书包(如"外贸单据核对""订单录入流程");
- 自动化(Automations):定时或触发的自动任务(如每日推送);
- 连接器与二进制:挂载的外部工具(最关键:lark-cli,飞书命令行工具,装在它的目录深处)。
2. 我们的历史:从 WorkBuddy 到 ZCode
某出口企业业务系统早期(2026 年 9 月前)构建在 WorkBuddy 上。迁移 ZCode 的原因与原则:
| 迁移动作 | 原则 |
|---|
技能包复制到 ZCode 技能目录(.agents/skills/) | 主副本原则:以 .agents 为准,WorkBuddy 侧视为旧拷贝 |
| 自动化任务在 ZCode 重建(每日推送/邮件维护等) | 单通道原则:同一职责只留一条自动化,旧侧停用防"双份推送" |
| 工作区规则与记忆迁入 ZCode 规则文件与记忆 | 规则随工作区走 |
迁移完成度:主线 100% 在 ZCode;WorkBuddy 侧保留三样"遗产"(见下章)。
WorkBuddy 使用与迁移指南 · 第 3/10 节 · 约 2 分钟
第二部分 现状盘点 · 还"活"着的三样东西
3. 遗产一:lark-cli 二进制(最重要,动不得)
全套构建与刷新脚本的飞书命令行工具,物理位置:
node_modules\@larksuite\cli\scripts\run.js
谁在依赖它(实测清单):看板构建脚本 _build_dashboard.py、返点文档生成 _build_rebate_fob.py、历史版本备份脚本等——即看板的每小时兜底刷新、每日数据更新,全部经由这条路径。删除或移动 .workbuddy 目录 = 看板数据链路瘫痪。
结论:.workbuddy 目录现状为"勿动"资产。 若未来要迁移 lark-cli(独立安装或换路径),必须走第九章的完整迁移流程,不许直接删。
4. 遗产二:旧自动化配置(只读)
WorkBuddy 侧残留一条旧自动化配置(历史上与 ZCode 侧每日推送重复,曾在 workbuddy 侧停用以防双份推送)。处置原则:保持停用现状、不删不改——它没有任何"必须保留的运行价值",但有"误启用即双份推送"的风险,动它没有收益。
5. 遗产三:旧技能拷贝(以主副本为准)
WorkBuddy 目录里有一批技能的旧拷贝(如外贸单据核对等)。使用原则:一律使用 ZCode 技能目录(.agents/skills/)的主副本——旧拷贝可能落后于主版本。判别口诀:"要用的去 .agents 找,workbuddy 里的当文物看。"
WorkBuddy 使用与迁移指南 · 第 4/10 节 · 约 1 分钟
第三部分 日常使用 · 现在还能怎么用
6. 用 lark-cli 干活(最常用)
虽然主线迁了 ZCode,但 lark-cli 本身仍是好用的飞书命令行工具。完整路径调用示例:
" node_modules/@larksuite/cli/scripts/run.js" auth status
日常写脚本时建议:把这条长路径存成变量(业务系统脚本都这么做),换工具时只改一处。常用命令(字段列表/记录读写/角色管理/API 逃生舱)详见《飞书使用指南》附录 A——两册命令通用,同一把 lark-cli。
7. 排障:依赖出问题时
| 症状 | 先查什么 |
|---|
| 构建报"CLI 异常"或文件不存在 | .workbuddy 目录是否被移动/清理;run.js 路径是否仍有效 |
| 飞书命令报权限/令牌 | 与 workbuddy 无关——走《飞书使用指南》第七章三道门排查 |
| 定时任务全挂但手动正常 | 回忆近期是否动过 .workbuddy;查运行记录找首次失败时间点 |
WorkBuddy 使用与迁移指南 · 第 5/10 节 · 约 1 分钟
第四部分 迁移 · 从依赖到独立
8. 迁移原则(三条铁律)
1. 一次只迁一样:lark-cli 路径/自动化配置/技能拷贝,分开迁移分开验证; 2. 双跑验证:新旧并行一段时间,结果一致才切; 3. 退役≠删除:旧目录改名归档(如 .workbuddy_retired_日期),观察一个月再清理。
9. lark-cli 独立化迁移手册(六步)
1. 独立安装 lark-cli(或复制二进制到中性路径,如 C:\tools\lark-cli\); 2. 全局搜索替换所有脚本里的旧路径(实测至少 4 个文件引用); 3. 手动跑一次看板构建,核对输出与行数(应仍为 数百行); 4. 强制触发一次定时任务,确认兜底通道正常; 5. 观察一个完整周期(含跨天),运行记录无异常; 6. 旧目录改名归档,不删。
10. 自动化迁移检查清单
- [ ] workbuddy 侧全部自动化已停用(防双份推送);
- [ ] ZCode 侧同等任务已建并验证至少一个周期;
- [ ] 两侧任务清单各留一份书面对照(哪条对应哪条);
- [ ] workbuddy 登录态/令牌过期不影响任何现役链路;
- [ ] 相关文档(MEMORY/README)已同步现状。
WorkBuddy 使用与迁移指南 · 第 6/10 节 · 约 2 分钟
第五部分 大师 · 平台思维
11. 平台通用概念对照(迁移即翻译)
WorkBuddy 与 ZCode 的概念几乎一一对应,理解了对照表,任何 AI 平台间的迁移都是"翻译题":
| 概念 | WorkBuddy | ZCode |
|---|
| 技能说明书 | Skills 技能包 | Skills 技能 + 规则文件(AGENTS.md) |
| 定时任务 | Automations | Automations(Cron 自动化)+ 系统计划任务 |
| 记忆 | 平台内记忆 | MEMORY 文件 + 工作区文档 |
| 外部工具 | 连接器/二进制挂载 | 命令行直接执行 + MCP |
| 权限 | 平台内配置 | 权限模式 + 钩子 + 硬闸 |
12. 多平台共存纪律
同时有多个 AI 平台时的纪律(项目实证教训):①一职责一通道(防双份推送);②主副本声明(哪个是权威写进文档);③依赖登记(谁引用谁,一笔一笔记清);④退役走流程(停用→观察→归档,不搞突然死亡)。
13. AI 平台的选型心法
选平台看四件事:①能力面(能否读写文件/跑命令/定时);②防护(权限模式/审计/回滚);③生态(与你现有数据源——飞书/Excel——的连接成本);④可持续(免费额度/导出自由度/迁移成本)。永远假设"未来会换平台"来设计——数据与规则放进开放格式(Markdown/JSON),把平台绑死的风险降到最低。业务系统的规则、口径、文档全是纯文本,这是今天能从容迁移的根本原因。
WorkBuddy 使用与迁移指南 · 第 7/10 节 · 约 1 分钟
FAQ
| 问题 | 答案 |
|---|
.workbuddy 目录能删吗 | 不能——lark-cli 在里面,删了看板数据链路瘫痪;迁移完成前为"勿动"资产 |
| 双份推送怎么发生的 | 两侧同名自动化同时活着;解法=旧侧停用(已完成),长期靠"一职责一通道"纪律 |
| 技能以哪个为准 | .agents/skills/ 主副本;workbuddy 侧是旧拷贝 |
| workbuddy 还会更新吗 | 以我们工作流为准:主线已迁 ZCode,workbuddy 仅作为 lark-cli 宿主保留 |
| 想彻底退役要多久 | 走第九章六步,建议观察一个完整周期(约 1 周),半天操作+一周观察 |
| 本册为什么没有产品全功能介绍 | 诚实边界:本册基于本项目工作区实证;产品全貌以 WorkBuddy 官方文档为准 |
WorkBuddy 使用与迁移指南 · 第 8/10 节 · 约 1 分钟
附录 A:依赖路径清单(实测 2026-10-27)
| 引用方 | 依赖路径 | 用途 |
|---|
_dashboard/_build_dashboard.py | .workbuddy/.../run.js | 看板构建拉飞书数据 |
_dashboard/_build_dashboard_v6/v7_backup.py | 同上 | 历史版本备份(同依赖) |
_scripts/_build_rebate_fob.py | 同上 | 返点 FOB 文档生成 |
| 定时任务 FZ_BoardRefresh_hourly | 经 _refresh_deploy.py 间接依赖 | 每小时兜底刷新 |
WorkBuddy 使用与迁移指南 · 第 9/10 节 · 约 1 分钟
附录 B:迁移检查清单(合并版)
□ 独立安装并验证 lark-cli → □ 全局替换脚本路径 → □ 手动构建对账 → □ 定时任务强制触发验证 → □ 跨天观察 → □ 旧目录改名归档 → □ 文档同步(MEMORY/README/本册)。
WorkBuddy 使用与迁移指南 · 第 10/10 节 · 约 1 分钟
附录 C:系列书目
《某业务系统技术文档》(系统档案)·《开发完全手册》(交付方法论)·《编程指南》(代码手艺)·《飞书使用指南》(平台:飞书)·《ZCode 使用指南》(平台:ZCode)· 本册(平台:WorkBuddy ①使用与迁移)。
Cloudflare 说明与国内替代 · 第 1/7 节 · 约 1 分钟
导语
2026-10-25 Dan 拟,供 Forrest 研究。结合咱们看板项目讲,不讲空泛概念。
Cloudflare 说明与国内替代 · 第 2/7 节 · 约 1 分钟
30 秒版
Cloudflare 是全球最大的网络基础设施公司之一(美股上市,代码 NET),在全球 300+ 城市有数据中心。一句话理解它的模式:把"服务器该干的事"搬到离每个用户最近的节点上。咱们的看板网页、实时接口、登录门禁,全都免费跑在它的边缘节点上——这就是为什么一个没有服务器的项目能做到"随时随地访问+秒级响应+带门禁"。
Cloudflare 说明与国内替代 · 第 3/7 节 · 约 1 分钟
一、咱们实际用到了它的什么(按项目对号入座)
| 功能 | 咱们用它干了啥 | 免费额度 |
|---|
| Pages(静态网站托管) | 看板网页本体 看板站点(门禁内);自动 HTTPS、全球加速、自动部署历史/回滚 | 无限站点/带宽,单文件 25MB |
| Pages Functions(边缘函数,咱们的 _worker.js) | /api/data 实时读飞书 + /api/record 白名单写回——代码跑在离用户最近的节点 | 每天 10 万次请求 |
| Access(零信任门禁) | 邮箱白名单+验证码登录,30 天会话;把整个站点(网页+接口)变成"只有自己人能看" | 免费 50 个用户 |
| Secrets(密钥保管) | 存飞书应用凭证、编辑令牌——密钥永不进网页源码 | 随函数免费 |
| _headers(安全响应头) | 全站 noindex 防搜索引擎收录 | - |
当前成本:0 元(全部免费档)。将来唯一可能付费的点:第 3 期推送方案里的 Durable Objects,需 Workers 付费档 $5/月(可选,不做不花钱)。
管理入口:dash.cloudflare.com(就是部署看板的那个账号,浏览器登录就能看到上面所有资源)。
Cloudflare 说明与国内替代 · 第 4/7 节 · 约 1 分钟
二、它还有什么(咱们暂时没用、但值得知道的)
- Workers KV / D1 / R2:边缘键值存储 / 边缘 SQLite 数据库 / 对象存储(类似 S3)——如果以后看板要存历史快照、审计明细,不用买服务器;
- Durable Objects:有状态的常驻小实例,第 3 期"秒级推送"方案里的广播器就是它;
- Tunnel(cloudflared):不开任何公网端口,把办公室电脑/内网的服务安全暴露到公网——如果以后想让外部访问咱们的本地工具,这是零信任的正确姿势(不用做端口映射);
- WAF / DDoS 防护 / DNS:它的老本行,全球一大半网站都在用它挡攻击;
- Wrangler CLI:咱们部署用的命令行工具;
- Pages 每次部署有独立预览地址+可一键回滚——改坏了随时退回上一版(咱们的 v7 备份+部署历史双保险)。
Cloudflare 说明与国内替代 · 第 5/7 节 · 约 1 分钟
三、"强大"在哪(原理层的三句话)
1. 边缘计算:传统架构=用户请求跑到遥远的中心机房;Cloudflare=请求落到最近的节点,咱们的 JS 代码就在那个节点上跑,飞书数据还缓存 30 秒——所以手机打开也快; 2. 零信任:过去"内部系统"要搭 VPN;Access 把登录墙做在云端,任何网址都能变成"自己人的内网",免 VPN、免买服务器; 3. 免费档慷慨:静态托管无限带宽这种事,传统云厂商不敢给——它靠企业级安全产品赚钱,开发者生态基本白送。
Cloudflare 说明与国内替代 · 第 6/7 节 · 约 2 分钟
四、国内有没有替代?
有,但要先讲清楚一个绕不开的前提:ICP 备案。
用国内云(腾讯/阿里等)做面向公众的网站托管+CDN,域名必须先做 ICP 备案(企业备案约 1~2 周流程);不备案就只能用海外节点或平台测试域名。Cloudflare 的 pages.dev 之所以免备案,是因为服务本身在境外——这也是当初"数据在境外"顾虑的来源,一体两面。
逐项对照
| 咱们的用法 | 国内对标 | 差异要点 |
|---|
| Pages 静态托管 | 腾讯云 EdgeOne Pages(最像,官方对标 CF Pages,有免费档)、阿里云 OSS+CDN、七牛/又拍 | EdgeOne 免费二级域名可用,国内加速节点需备案域名;阿里系同理 |
| 边缘函数 | 腾讯云函数计算/EdgeOne Functions、阿里云函数计算 FC | 能力对得上,生态/文档不如 Workers 顺手;冷启动略慢 |
| Access 门禁 | 腾讯 iOA 零信任、阿里云 IDaaS | 企业级、按人收费、配置重,为小团队不划算;国内更常见的做法是"挂在飞书/企微里,靠 IM 登录" |
| 整体替代 | 迁进飞书生态(妙搭托管+飞书扫码登录) | 最顺的"国内替代":数据留在飞书(字节国内机房)、登录=飞书身份、门禁天然、零备案——就是 10.25 讨论过的迁移路线,代价是页面要在妙搭重做 |
结论建议(维持原判,补充新信息)
1. 短期维持 Cloudflare:免费、免备案、已建成、Access 门禁已生效;数据敏感度(订单商务信息+HTTPS+白名单)风险可控; 2. 若"数据不出境"成为硬要求:首选整体迁飞书生态(妙搭),一步解决门禁+出境+国内访问速度;次选腾讯 EdgeOne Pages(接受备案流程后国内体验更好); 3. 混合折中(不存在完美方案):网页托管国内+数据照走飞书 API——意义不大,因为网页里内嵌的 data.json 快照本身就是业务数据,托管在哪数据就在哪。
Cloudflare 说明与国内替代 · 第 7/7 节 · 约 1 分钟
五、咱们账号里的资产清单(方便你登录后核对)
- Pages 项目:
order-board(每次部署有历史记录,可回滚) - Secrets×3:
FEISHU_APP_ID / FEISHU_APP_SECRET / EDIT_TOKEN(编辑令牌) - Zero Trust 团队:
young-frog-452f;Access 应用:订单看板(邮箱白名单在这里改) - 域名:无自有域名(用的 pages.dev 二级域)
*关联文档:飞书实时互联_方案计划_20261025.md(总纲)· 第3期_秒级推送方案_20261025.md(推送详设)· 本篇(平台与替代对照)。*