Live Code + Opencode 周期性任务拆解与实现操作规范（SOP）
0. 文档属性
- 适用对象：使用 live code 软件与 opencode（代码型 LLM 代理）完成自动化/半自动化任务的执行人员
- 适用任务：周期性重复任务（网页查询、数据库增量更新、定期报表）、一次性数据整理、带有语义判断/文本理解的复杂任务
- 目标：将“需求”稳定转化为“可运行、可复用、可审计、可维护”的工作流，并为 AI 自动生成 opencode 提示词提供标准输入与模板
1. 基本术语与组件定义
1.1 组件分层（推荐统一认知）
- 需求层：用户想要的结果（例如：每周检查余额、监控某数据库是否新增样本、整理并汇总数据）
- 流程层（Playbook）：任务步骤编排（按顺序执行哪些动作，失败如何处理）
- 工具层（Tools）：对外部系统的访问方式
- API 调用、数据库查询、网页自动化（浏览器驱动）、文件系统读写等
- 执行层（Code/Scripts）：可确定性执行的代码（抓取、解析、去重、入库、导出）
- 推理层（LLM/Opencode）：用于不易规则化的部分（语义抽取、归类、异常解释、生成报告文字等）
- 配置层（Configs）：变化的参数（账号、目标疾病关键词、时间窗口、输出格式、调度频率）
- 数据层（Storage）：sqlite/文件/对象存储，存放元数据、运行记录、结果快照
1.2 “固化方式”名词约定
- 一次性提示词（Prompt-only）：每次用长提示词直接让 opencode 临时写/跑逻辑
- 脚本（Script）：单文件或少量文件，可直接运行，输入输出明确
- 技能（Skill）：可复用的“函数/模块/命令”，接口稳定（例如
check_balance(config)） - 插件/集成（Plugin）：在 live code/代理框架中注册的扩展
- MCP 工具（MCP）：通过结构化协议把外部能力（浏览器、数据库、私有系统）暴露给代理调用，强调强约束输入输出与权限隔离
统一原则：越靠近外部系统、越涉及凭证与稳定性，越应工具化（Plugin/MCP）；越通用、越高频，越应 Skill 化；越探索、越一次性，越适合 Prompt-only。
2. 总体原则（类似“临床路径”的硬规则）
- 稳定接口优先固化：外部系统、数据库 schema、输出报表结构一旦稳定，应固化为代码/skill/tool；Prompt 只负责“选择与编排”。
- 变化参数配置化：所有可变项（查询关键词、时间范围、输出字段、阈值、账号别名）写入配置文件，不写死在提示词。
- 可审计：每次运行必须落地：运行时间、输入参数版本、外部请求摘要、结果行数、差异数量、错误堆栈（必要时脱敏）。
- 幂等与增量：周期性任务默认按增量设计（仅拉取“新增/更新”），并可重复执行不产生重复数据。
- 优先官方 API，其次网页自动化：网页解析对 UI 变化敏感，维护成本高；能用 API/导出接口就不用抓页面。
- 最小权限与密钥隔离：凭证不得写入提示词与代码仓库；使用环境变量/密钥管理；日志脱敏。
- LLM 用于语义，不用于“编造事实”：LLM 输出必须被结构化（JSON/schema）并校验；可疑内容需回溯来源或标注“不确定”。
3. 固化策略决策规范（Prompt vs Script vs Skill vs Plugin/MCP）
3.1 决策矩阵（按任务特征选择固化方式）
| 任务特征 | 推荐固化形态 | 说明 |
|---|---|---|
| 低频（≤1次/月）、需求不稳定、探索性强 | Prompt-only | 允许快速试错，不投入工程化 |
| 中频（每周/每月）、逻辑确定、输入输出明确 | Script | 一键运行，最小工程投入 |
| 高频（每日/每周）、多任务复用相同能力 | Skill + Config | 把“稳定步骤”沉淀为模块，参数进配置 |
| 涉及账号/凭证/外部系统访问、需权限控制 | Plugin/MCP + Skill | 把“访问能力”工具化，LLM 只调工具 |
| 同时包含确定性步骤 + 复杂语义整理 | Hybrid：Code 负责确定性 + LLM 负责语义 | 用“LLM 步骤”嵌入流程，输出结构化并校验 |
3.2 固化边界划分法（必须执行）
对每个任务将步骤拆成两类：
-
A 类：可确定性步骤（必须代码化）
典型：登录、请求、抓取、解析、清洗、去重、入库、导出、差异比对、失败重试
→ 产物：Script/Skill/Tool -
B 类：语义/判断步骤（可 LLM 化）
典型：从描述中抽取字段、把样本按主题归类、生成报告摘要、解释异常原因、生成邮件正文
→ 产物：LLM Prompt（结构化输出 + 校验 + 追溯）
“复杂度高”不是不固化的理由。复杂任务应先拆成 A/B，再把 A 固化，B 作为受控模块嵌入。
4. 标准作业流程（从需求到上线运行）
4.1 需求采集（Task Intake Form）
每个任务必须填写以下字段（作为 AI 写 opencode 提示词的输入）：
- 任务名称：唯一标识（如
balance_audit/geo_monitor_disease_x） - 目标：一句话定义成功（“输出最新余额列表并与上次对比差异”）
- 触发方式：手动/定时（cron）/事件触发
- 频率：例如每日 09:00 / 每周一
- 数据源：网页/API/本地 sqlite/文件夹
- 输入参数：关键词、账号别名、时间窗口、输出字段等
- 输出物：文件格式（CSV/Excel/Markdown/HTML/PDF）、存放路径、命名规范
- 验收标准：可检查的标准（行数>0、字段齐全、差异统计、错误=0）
- 约束与合规：访问频率限制、需要脱敏字段、禁止写入日志的信息
- 失败策略：重试次数、降级方案（如改为手动导出）、告警方式
4.2 任务拆解（Step Decomposition）
将任务拆成“最小可测试步骤”，并为每步补齐“五要素”：
- 输入：来自哪（文件/DB/网页/API）
- 处理：确定性处理还是 LLM 语义处理
- 输出：产出什么（结构化数据/文件/日志）
- 校验：如何判断正确（schema/数量/哈希/对账）
- 失败处理：重试/跳过/终止/告警
建议使用统一表格（示例）：
| Step | 名称 | 类型(A/B) | 输入 | 输出 | 校验 | 失败处理 |
|---|---|---|---|---|---|---|
| 1 | 读取配置 | A | YAML | 参数对象 | 必填字段齐全 | 终止并报错 |
| 2 | 拉取数据 | A | API/网页 | 原始响应 | 状态码/元素存在 | 重试+截图 |
| 3 | 解析标准化 | A | 原始响应 | DataFrame | schema 校验 | 记录坏行 |
| 4 | 去重增量入库 | A | DataFrame+sqlite | 新增记录数 | 主键唯一 | 回滚事务 |
| 5 | 差异对比 | A | 当前+历史 | diff 报告 | diff 合理 | 标记异常 |
| 6 | 语义摘要 | B | diff+样本描述 | JSON 摘要 | JSON schema | 重新提示/降级 |
| 7 | 导出与通知 | A | 报告对象 | 文件+消息 | 文件存在 | 告警 |
4.3 技术实现选型（Implementation Planning）
对每一步选择实现方式：
- 访问外部系统：优先 API；如必须网页自动化，选用浏览器驱动并做选择器版本管理
- 解析与清洗：Python/JS 代码确定性实现
- LLM 部分：仅处理“语义/总结/归类”，输入输出结构化
- 数据存储：sqlite（元数据、运行记录、快照）+ 文件输出（报表）
4.4 工程结构规范（目录与命名）
推荐统一项目结构（示例）：
project/
configs/
balance_audit.yaml
geo_monitor.yaml
skills/
balance_check.py
geo_sync.py
report_render.py
llm_enrich.py
scripts/
run_task.py
mcp_tools/ # 如使用 MCP
browser_tool/
db_tool/
data/
sqlite/
metadata.db
snapshots/
outputs/
reports/
logs/
docs/
SOP.md
PLAYBOOKS.md
4.5 测试与验收（Testing）
最少包含三类测试：
- 单元测试：解析器、去重逻辑、schema 校验
- 集成测试（Dry-run）：对外部系统只跑到“获取并解析”，不写入最终库或写入临时库
- 回归测试：外部页面/接口变更后，能快速定位失效点（截图/响应快照）
4.6 上线运行与调度（Runbook）
- 手动运行命令：统一入口（如
python scripts/run_task.py --task xxx --config configs/xxx.yaml） - 定时任务：cron/任务调度器调用同一入口
- 并发与锁：同一任务同一时间只允许运行一次（文件锁/DB 锁）
- 告警：失败告警 + 数据异常告警（例如新增数量异常、字段缺失）
4.7 运行记录（必须落库/落文件）
每次运行至少记录：
- run_id、开始/结束时间、配置版本 hash
- 拉取来源（URL/API endpoint）摘要
- 新增/更新/删除统计
- 输出文件路径与 hash
- 错误堆栈与截图路径（若网页自动化）
5. Opencode 提示词编写规范（用于“执行编排”而非“写死逻辑”）
5.1 提示词的基本定位
- 提示词负责：选择任务、装载配置、调用既有 skill/tool、组织输出与验收
- 提示词不负责：长期维护的抓取/解析细节（应在代码中）
5.2 标准提示词模板（可直接复用）
以下模板用于让 AI 生成/执行 opencode 指令（可作为固定“母模板”）：
《任务执行提示词模板》
- 任务标识：
<task_name> - 目标：用一句话描述最终交付物
- 输入：配置文件路径、数据库路径、必要的环境变量名（不填具体密钥）
- 输出：报告路径、输出格式、摘要字段
- 工具/约束：允许使用的命令、禁止输出敏感信息、限速/重试策略
- 执行步骤（必须按顺序）：
- 读取配置并打印“脱敏后的参数摘要”
- 运行 dry-run（如适用）
- 正式运行并生成报告
- 运行验收检查（schema/行数/差异统计）
- 汇总运行结果（含关键指标与输出路径）
- 失败处理：失败时输出定位信息（日志位置、截图位置、失败 step）
- 验收标准：明确可机器验证的条件
- 交付格式：最终在终端输出一段“运行摘要”+ 生成文件
5.3 结构化输出要求（强制）
LLM 参与的步骤输出必须是JSON（或可解析结构），并通过 schema 校验：
- 例：摘要输出必须包含字段：
summary,highlights[],risks[],confidence,evidence_refs[]
若校验失败：
- 自动触发一次“纠错提示词”重试（最多 N 次）
- 仍失败则降级为：输出原始 diff + 标注“未生成摘要”
6. Skill / Plugin / MCP 的设计规范（让复用变得可控）
6.1 Skill 设计（推荐接口形式）
- 输入：
config（字典/对象）+ 必要的运行时上下文（路��、logger、db 连接） - 输出：结构化结果对象（含统计指标、数据集引用、输出文件路径）
- 约束：
- 不直接读写全局状态（除非明确）
- 可注入依赖（便于测试）
- 默认幂等（重复运行不产生重复记录）
6.2 MCP/插件设计（适用于外部系统与凭证）
适用场景：
- 需要浏览器自动化、登录态、cookie 管理
- 需要访问内部系统/私有 API，必须做权限隔离与审计
- 需要统一的速率限制、重试、熔断
规范要求：
- 强类型输入输出：使用 JSON schema 或等价约束
- 最小权限：工具只提供必要动作（如
open_url,click,extract_text,download_file） - 审计日志：每次调用记录“做了什么”，但不记录敏感值
- 失败可诊断：返回错误码、错误信息、可选截图/响应片段路径
- 稳定契约：工具升级版本化，避免破坏性变更
7. 数据治理与 sqlite 增量设计规范（适用于“元数据已入库”的场景）
7.1 sqlite 推荐表（最小集合）
runs：记录每次运行run_id,task_name,started_at,ended_at,config_hash,status,stats_json,log_path
items：领域对象元数据（例如数据集/样本/套餐条目）source,source_id（主键之一）,title,updated_at,raw_json,fingerprint_hash
seen：去重与增量标记source,source_id,first_seen_at,last_seen_at,last_fingerprint_hash
diffs：每次运行的变更摘要run_id,source_id,change_type（NEW/UPDATED/REMOVED）,diff_json
7.2 增量算法（必须实现）
- 主键：
(source, source_id) - 指纹：对关键字段（标题、日期、样本数、平台等）做 hash（fingerprint）
- 若
source_id不存在 → NEW - 若存在但 fingerprint 变化 → UPDATED
- 若本次未出现且允许“缺失判定” → REMOVED（可选）
8. 复杂数据整理与 LLM 协作规范（避免“固化难”）
8.1 拆解原则：把复杂度分摊到流水线
复杂整理任务按以下顺序组织，前四步必须代码化：
- 抽取（Extract）：读入原始数据/网页/API 响应
- 标准化（Normalize）：字段统一、类型转换、单位换算
- 约束校验（Validate）：schema、必填、取值范围
- 确定性处理（Deterministic Transform）：去重、聚合、匹配、排序
- LLM 语义增强（Semantic Enrich）：
- 分类、要点提取、异常解释、生成摘要
- 输出必须结构化并可回溯证据
- 回写与导出（Persist & Export）：写库、导出报表
固化的重点在 1–4；LLM 仅插入第 5 步，且第 5 步可以替换/禁用，不影响主流程产出。
8.2 LLM 步骤的“可控化”要求
- 输入限制：仅提供必要字段与证据片段（避免喂入无关噪声）
- 输出限制：JSON + schema 校验 + 置信度字段
- 追溯：输出中必须包含
evidence_refs（指向原始记录 ID 或行号） - 降级策略：LLM 失败不阻断核心数据更新，只缺少语义报告
9. 两类典型任务的标准 Playbook（可直接套用）
9.1 Playbook A：网页查询类（例如余额巡检）
目标：定期从网页获取结构化信息，形成历史记录与差异报告
步骤：
- 读取配置：目标站点、账号别名、查询路径、字段映射、限速参数
- 获取登录态：优先复用 session；不行则走登录流程（如需人工介入，明确“暂停点”）
- 导航并提取：定位元素→提取文本/表格→结构化
- 标准化：数值清洗、币种/单位统一
- 入库与快照：保存原始页面快照/截图（可选）、结构化数据入 sqlite
- 差异对比：本次 vs 上次（数值变化、缺失项）
- 生成报告：表格 + 差异摘要 + 异常标记
- 告警：失败或异常阈值触发通知
强制注意：
- 页面选择器应集中管理并版本化（避免散落在提示词）
- 任何凭证不得进入日志/报告
- 对 UI 变化准备“快速定位材料”：截图、HTML 片段、最后成功的选择器版本
9.2 Playbook B：数据库/公共数据源增量监控（例如 GEO 更新）
目标：以“增量同步”为核心，避免重复抓取与重复入库
步骤：
- 读取配置：查询关键词、过滤条件（物种/组织/平台/时间）、分页/限速
- 查询索引：拿到候选条目 ID 列表
- 与 sqlite 比对：找出未见过或 fingerprint 变化的条目
- 拉取详情：仅对 NEW/UPDATED 拉详情（节流）
- 解析标准化：统一字段集，保留原始 JSON 以便追溯
- 入库：事务写入 items/seen/diffs
- 输出：新增/更新清单、关键字段变化、可选 LLM 摘要
- 记录运行：runs 表写入统计与输出路径
10. 交付物规范（新人执行的“最终产出”必须长这样）
每个任务至少交付三类产物：
- 可运行入口：一条命令即可跑（或一个按钮/任务配置）
- 配置文件：可复制修改以扩展到新账号/新疾病
- 报告与日志：
- 报告：
outputs/reports/<task>/<date>.<ext> - 日志：
logs/<task>/<run_id>.log - 运行摘要（终端输出）：新增数、更新数、输出路径、耗时、失败 step（若有）
- 报告：
11. AI 自动生成 opencode 提示词的“生成算法”（供上传给 AI）
当收到任意需求时，必须按以下顺序生成 opencode 提示词（不得跳步）：
- 抽取任务字段：按“需求采集表”填充（缺失则使用默认值并显式标注）
- 分类：网页/API/数据库/文件；频率；是否涉及凭证；是否需要 LLM
- 拆步：按“Step Decomposition”输出 6–12 个最小步骤
- 固化决策：
- A 类步骤 → 指向既有 script/skill/tool；若不存在则先生成代码骨架
- B 类步骤 → 生成结构化 LLM 子提示词（含 schema）
- 组装提示词：使用《任务执行提示词模板》，并引用：
- 配置路径
- 运行入口命令
- 验收脚本/检查点
- 输出验收清单：给出可机器验证的检查项（文件存在、行数、schema、diff 统计等）