nkg-ai-flow-skill

自定义 Flow 开发规范

硬规矩

把 flow 当作可运行的 app,不是孤立的 JSON。下面这些做不到就别合：

• 用 TypeScript FlowBuilder 写图,JSON 只作为生成产物。
• 优先组合内置节点;只有真的需要复用领域逻辑、严格 schema 校验、复杂解析时才写自定义节点。
• 数据血缘必须显式:每个非根节点都要消费上游输出、累计 context、或显式静态配置,绝不依赖"前一个节点大概干了什么"。
• 文件读写、命令执行、迭代验证、产物落盘走内置 agent 节点,确定性节点不要伪装能干这些。
• 严禁造假/fallback 调用第三方依赖:LLM、联网搜索、HTTP/工具调用、向量库、外部服务等节点,任何环境(开发、调试、smoke、单元测试、CI、生产)都必须走真实调用。失败就硬失败,不准 mock、stub、写死返回值、catch 后返回伪造数据。
• 环境变量读取必须走 VariableStore:任何节点、runner、smoke、CLI 都禁止直接读 process.env、禁止自己 dotenv.config()、禁止在 app/scripts 目录新建 .env* 文件冒充配置源。
• 配置走 flow 同目录的伴生 JSON,不依赖 .env.local。
• 控制边表达顺序,数据边表达依赖,两者分开。
• 验收用最窄的 build / typecheck / 针对性 smoke,集成 smoke 留到最后。

起步参考

写代码前先看最近的本地范例,凡是已有 app 干过类似的事,扩展它的模式而不是另起炉灶：

设计流程

1. 写下 flow 合同(注释或 README,关键是源文件可见):flow_id / purpose / caller_input / final_output / must_use_tools_or_services / must_not_do / acceptance_checks。

2. 选 app 形态：

不要为普通的 prompt 模板或简单字符串/对象 reshape 写自定义节点,用 llm / text_input / transform。

Advisor 监督 Flow

需要观察、指导或门控业务 Run 时，把 Advisor 当成可选高级运行时能力，不要把监督节点硬塞进业务 Flow：

• 业务 Flow 保持独立可运行；只有确实需要响应建议的 Agent/自定义节点才读取 ctx.guidance。
• 审阅逻辑写成普通、可版本化的 Advisor Flow，再用 createFlowAdvisorReviewer(...) 选择其审阅节点。
• 用 AdvisorRuntime 在运行入口绑定业务 Flow 与 reviewer；模式按需求选择：observe 只记录、steer 向后续节点投递 concern/blocker、gate 遇 blocker 在安全节点边界暂停。
• Reviewer 输入是增量 AdvisorReviewBatch；输出为单条 advisory 或 advisories[]，每条至少包含非空 code、message，可带 severity、suggestion、evidence、dedupeKey。
• Reviewer 每次更新只发一条真正有行动价值的建议；禁止输出 done、complete、LGTM 等无内容消息，稳定问题必须设置可复用 dedupeKey。
• 可能产生 blocker 时调用 AdvisorRuntime.start()，监听 run_suspended 后由人工或外部策略调用句柄的 resume()；不要用 invoke() 等待一个无人恢复的 gate。
• 暂停只阻止后续节点启动，不中断已经执行的节点；当前是进程内安全边界暂停，不得宣称支持进程重启后恢复。
• Advisor 失败默认 fail-open；不能让观察器故障把主业务 Run 误判为失败，也不能给 Advisor 默认开放写文件或 bash。