AI协作工具的开发原则_2026-08-12_13-14-11.md
AI协作工具的开发原则
关键观点总结
- AI 的长处是理解自然语言、识别意图、结合上下文追问、规划步骤、生成候选方案和编排工具；程序的长处是确定、重复、可测试地计算、校验、执行、保存和审计。
- 不应让 AI 成为唯一的执行者或事实来源。AI 可以发起和组织操作，但业务规则、数据写入、权限判断和高风险执行必须由程序承接。
- 软件设计应从真实的用户目标和用户故事出发，先发散场景，再按价值、频率、风险、成本和闭环能力筛选，不应从模型能力或技术栈出发。
- 用户故事应先提炼为稳定的领域能力和对外契约；GUI、AI、规则引擎、定时任务和脚本都通过同一套能力调用系统。
- 接口应面向业务意图，例如记录数据、创建观察列表、生成回顾、安排同步；不应把任意数据库更新、任意文件写入或任意系统命令直接暴露给 AI。
- 每项能力需要可发现、可校验、可解释：定义名称、输入结构、前置条件、结构化结果、错误类型、幂等性、风险等级、事实来源和可读回执。
- 按风险划分执行状态：查询和无副作用分析可直接执行；低风险写入可执行并留痕；有影响的操作采用“预览 -> 确认 -> 执行 -> 回执”；不可逆、资金或对外操作需要更强的审批、权限和审计。
- 先用一两个高价值的真实场景完成闭环，再由真实使用中发现的共性推动抽象和平台化，不要先构建过度通用的框架。
完整对话过程
初始想法：AI 是意图层，程序是执行层
提出的核心想法是：AI 擅长理解自然语言，可以用于意图识别；让 AI 执行重复且确定的事情是一种浪费，应由程序承担。软件可提供能被 AI 调用的接口，用户既能通过 GUI 操作，也能直接表达目标；AI 识别意图、选择合适接口和参数并交给程序执行，从而提升效率和易用性。
讨论形成的核心判断是：
AI 负责把人的模糊目标翻译成结构化操作；程序负责可靠、可验证、可重复地执行操作。
GUI、脚本、定时任务和 AI 不应各自拥有一套业务逻辑，而应全部落到同一组稳定的领域能力上。AI 不应直接理解或修改底层数据结构，也不应绕过业务规则；它的职责是选择正确的能力、补全参数，或在信息不足时向用户追问。
例如，健康工具可以提供“记录体重”“查询趋势”“生成运动计划”等能力。用户可以通过页面录入，也可以告诉 AI“记录今天的体重，并看看离本月目标还有多远”。无论入口是什么，最终都调用相同的程序能力。
这里需要避免把“不要让 AI 做确定性工作”理解成完全不允许 AI 参与。AI 可以发起重复操作或编排多个步骤；但求和、筛选、状态转换、数据写入、权限检查、设备控制和固定格式输出，应由程序执行。这样既保留自然语言交互的便利，也获得确定性、可测试性、可审计性和可复现性；即使 AI 不可用，GUI 与自动化仍可运行。
从用户故事到对外契约
提出的软件开发路径是：先定义用户故事，头脑风暴尽可能多的使用场景；选择有价值的部分；设计相应接口以定义对外契约；最后再选择语言和内部架构来满足这些接口需求。
该路径被进一步整理为：
真实目标与约束
↓
用户故事与场景库
↓
筛选高价值、可闭环的场景
↓
领域能力与对外契约
↓
GUI / AI / 自动化共用的调用入口
↓
内部架构、数据模型、技术选型与实现
在“用户故事”和“接口”之间，还应有“领域能力”这一层。用户故事常常描述一个完整目标，不一定等于一个单独的接口。例如“判断本月目标是否仍可完成，并调整接下来一周的计划”可能需要查询记录、评估目标进度、生成候选计划和保存确认计划等多项能力。AI 负责理解目标并编排这些能力，程序负责确保数据和执行结果可靠。
用户故事还应同时描述成功路径与边界条件，包括重复提交、参数缺失、数据源不可用、撤销、权限、预览确认和结果可见性。由此得到的不只是一个可调用接口，而是一份可信赖的产品契约。
接口契约的内容与边界
接口不只是传输格式，而是产品能力边界。每项能力至少应明确：
- 能力：系统帮助用户完成什么业务动作；
- 输入：需要哪些信息、类型、范围和缺失信息的处理；
- 输出：事实数据、计算结果、候选方案或执行回执；
- 状态：例如未执行、已预览、待确认、已执行、失败；
- 约束：权限、风险等级、幂等性、可撤销性和审计要求；
- 解释：执行依据、使用的数据和规则，以及给用户的可读说明。
对 AI 而言，接口还应提供机器可读的元数据，使其知道能做什么、不能做什么、调用会造成什么影响。可以包含能力名称、描述、风险等级、执行方式、输入结构、结果结构、假设与警告等信息。
例如，“生成计划”可以被定义为预览型能力：它生成候选结果但不自动保存；用户确认后，再由明确的保存能力落地。底层传输可以是 HTTP、MCP、CLI、进程内调用或消息命令，但这些都应位于能力模型之后。
应避免将数据库遥控器或系统遥控器直接提供给 AI，例如任意 SQL 执行、任意表更新、任意文件写入或任意命令执行。这些接口虽然灵活，却会绕开业务约束、放大误操作风险，也难以审计。更好的方式是暴露业务动作，如“记录数据”“创建观察列表”“生成回顾”“安排同步”等。
风险控制与执行模型
自然语言的灵活性不能等同于无条件执行。系统应区分查询、建议、预览操作、立即操作和需要确认的操作。
建议的执行边界为：
查询 / 无副作用分析：直接执行
低风险写入：执行并留下可追溯记录
有影响的操作：预览 -> 用户确认 -> 执行 -> 结构化回执
不可逆、资金或对外操作：更强的权限、审批与审计
高风险场景中，AI 可以分析、提出方案或创建待审核操作，但不应因为一句自然语言就直接完成实际执行。系统应让用户可以看清即将发生什么、依据是什么、最终是否成功。
已确定的开发原则
- 从真实用户故事出发，不从 AI 功能或技术栈出发。 先列场景，再按价值、频率、风险、成本和闭环能力筛选。
- 先定义领域能力和契约，再做 GUI、AI 接入与内部实现。 对外协议只是能力的载体。
- 一套业务能力，多种入口共享。 GUI、AI、规则、定时任务和脚本调用同一套领域命令与查询。
- AI 负责不确定性，程序负责确定性。 AI 做理解、追问、规划、编排和解释；程序做计算、校验、执行、保存和证明。
- 接口面向业务意图，不暴露底层实现。 以业务动作定义能力，不把底层存储或任意系统操作交给 AI。
- 每项能力都应可发现、可校验、可解释。 明确输入、前置条件、结构化输出、错误、幂等、风险与依据。
- 按风险设计执行状态。 用预览、确认、执行、回执和审计来匹配操作影响，而不是默认一句话立即生效。
- 先完成小而真实的闭环，再扩展通用性。 从真实使用中发现共性，再抽象为平台能力、插件或规则。
最重要的红线是：
AI 可以建议、调用受约束的能力和解释结果，但不应绕过领域规则直接改写事实数据或执行高风险动作。
可复用的架构关系
用户目标
├─ GUI：直接选择和编辑
├─ AI：理解、追问、规划、编排
└─ 自动化：按条件触发
↓
统一的领域能力契约
↓
校验 / 权限 / 风险控制 / 审计 / 幂等 / 事务
↓
数据库、文件、设备、外部 API、消息系统
该原则集既可用于轻量的个人工具，也可用于未来的可配置软件平台；变化的是实现规模和技术选型，不变的是以稳定能力模型为中心、让 AI 成为自然语言编排层的设计方向。
浙公网安备 33010602011771号