// Package sections 提供引擎层可复用的 PromptBundle Section 库.
//
// 这些 Section 是跨行业中立的技术工具原语, 消费层 (platform/ 或第三方)
// 的 PromptBundle 实现通过 import 本包, 在 StaticSections/DynamicSections
// 里引用这些 Section, 避免从零写相同的技术行为提示词.
//
// 设计边界 (L952d, 2026-04-17):
//   - 引擎层只出**技术工具原语 Section** (DB / SSH / SystemConfig 等)
//   - 行业 / 角色 Bundle (SRE / DBA / WMS / HIPAA 等) 是消费层职责
//   - 对齐 CLAUDE.md 原则 9 "引擎核心不假设特定场景"
//
// 命名约定: 导出变量名即 Section.Name (首字母大写驼峰, 底层 name 用 snake_case).
// 便于消费层直观引用:
//
//	type MyIndustryBundle struct{}
//	func (MyIndustryBundle) StaticSections() []*context.Section {
//	    return []*context.Section{
//	        sections.DBOps,            // 引擎提供的 DB 行为准则
//	        customBusinessSection,     // 消费层自定义的行业 section
//	    }
//	}
//
// 风格对齐: Section 文本对齐 core/pkg/context/prompts_zh.go 的早期方案编程
// Bundle 风格 (markdown header + bullet, 口语化直述, 硬约束与软引导分层).
package sections

import "git.flytoex.net/yuanwei/flyto-agent/pkg/context"

// DBOps 是数据库操作的行为准则 Section.
//
// 覆盖四块技术行为:
//  1. 读取数据 — 判断力引导, 不硬性 LIMIT (早期方案 GrepTool head_limit 同策略:
//     工具层默认值 + 显式 override 路径, 提示词只管判断力)
//  2. 写前 Dry-run — 硬约束, 不可逆写必走 (呼应消费层 TODO L1011-1017)
//  3. 并发安全 — CAS + 短事务 + 影子表
//  4. 危险操作强制确认 — DROP/TRUNCATE/ALTER/无 WHERE 删改
//
// 跨行业中立: 不出现"库存"/"订单"/"病历"等业务词. 业务约束由消费层 Bundle
// 的其他 Section 补充 (Section 库只管"怎么操作数据库", 不管"什么业务数据").
//
// 静态 Section (Static=true), 全局缓存, Engine 生命周期内不重算.
//
// 升华改进(ELEVATED): 早期实现 无对应 Section — 早期方案是编程助手,
// DB 操作通过 Bash + 第三方 CLI (psql/mysql) 走, 没有 DB 工具的专门提示词.
// 本 Section 是 Flyto 作为"跨行业 Agent 引擎"首次提供的 DB 行为准则,
// 与消费层 DB 工具链 (L1011-1017) 言行互证.
var DBOps = context.StaticSection("db_ops", dbOpsText)

// dbOpsText 是 DBOps Section 的提示词文本.
//
// 设计原则:
//   - 硬约束 (写前 Dry-run / CAS / 危险操作确认) 用 "必须" 保底
//   - 软引导 (读取判断力) 用 "优先/预感/显式交代" 留判断空间
//   - Checkpoint 机制以 cross-reference 方式引用, 不重复实现细节
const dbOpsText = `# 数据库操作

数据库是持久化副作用工具,错误通常不可逆.使用 DB 工具时遵守以下行为准则.

## 读取数据

 - 工具层对读操作默认设置行数上限(如 LIMIT 1000),防止意外把全表拖进上下文.
   这个默认值适合抽样、schema 验证、debug 查看数据长相等探索性场景.
 - 当任务确实需要全表(聚合统计、完整性校验、全量导出),显式传 limit=0
   或工具提供的 full_table 参数,并在工具调用说明里交代为什么需要全表,
   让用户知道你做了判断.
 - 预感结果会很大时,优先用工具提供的分页(cursor/offset)或 streaming 模式,
   不要一次把几十万行拉到内存.
 - 能用 SELECT 解决的查询,永远不要用 UPDATE/DELETE 去"试试看".

## 写入数据 — 先演练再提交

 - 所有写操作(INSERT/UPDATE/DELETE)必须先用 Dry-run 工具生成 diff,
   让用户看清"改了哪些行、改成什么样",用户明确确认后再真正提交.
 - Dry-run 失败时不要直接跳到真提交,也不要重试 Dry-run 超过一次.
   把失败原因告诉用户,让他决定下一步.
 - 写操作的作用范围(行数、表、schema)越清晰越好.WHERE id = 42 优于
   WHERE name LIKE '%x%';如果必须模糊匹配,先用 SELECT 把候选行数亮给用户.

## 并发安全

 - 读写混合场景用乐观锁(CAS):读出一行的 version 字段 → 本地修改 →
   写回时把"期望 version"作为 WHERE 条件.写回影响行数为 0 即冲突,
   重新读取再试,最多 3 次;3 次仍失败则上报,不再盲目重试.
 - 事务尽量短.单个事务超过 10 秒基本是设计问题,停下来告诉用户,不要硬撑.
 - 多轮推理里需要临时存中间状态时,用工具提供的影子表或 staging 表机制,
   不要污染正式表.会话结束时工具会自动清理.

## 危险操作 — 必须让用户按确认

以下操作即使看起来"只是验证想法",也必须让用户在引擎 Checkpoint 里手动
确认,不要试图绕过或预判用户意图:

 - DROP TABLE / DROP DATABASE / DROP INDEX
 - TRUNCATE TABLE
 - ALTER TABLE 结构变更(加/减/改列、改类型、加索引)
 - 不带 WHERE 的 DELETE / UPDATE
 - 跨库 / 跨 schema 的批量操作

工具层的 Checkpoint 机制会自动识别这些模式并要求用户确认;不要试图通过
拼 SQL 的方式绕过识别.`