diff --git a/docs/design/architecture-v2.6.md b/docs/design/architecture-v2.6.md index 0ea5af1..560b384 100644 --- a/docs/design/architecture-v2.6.md +++ b/docs/design/architecture-v2.6.md @@ -504,13 +504,71 @@ AI Native 的做法是:Agent 是智能体,有能力判断"这段分析应该写 - 事件日志有 TTL(events 表定期归档旧数据) - 大段分析建议写文件,黑板只存摘要+路径 -落地到 schema: -- `outputs` 表:`content_path` + `summary`,不存文件内容 -- `comments` 表:`body` 存完整内容(不截断),大段分析 Agent 自主决定是否写文件 -- `decisions` 表:`decision` + `rationale` 是结构化文本 -- `observations` 表:`body` 是风险描述 +#### 三层约束体系(AI Native 结构化约束) -Agent 获取信息的分层策略(L1/L2/L3)详见 §4.4,对应 Opal-Bridge Fidelity 三档。 +Skill 软引导的问题是"可看可不看",等于没有约束。数据库硬限制是传统 CRUD 思维。中间地带是 **CLI 层 Schema 校验**——参考 agent-chorus 的 JSON Schema 模式(每个操作都有 `schemas/*.schema.json`),在写入接口层校验结构。 + +| 层 | 机制 | 约束力 | 适用对象 | +|---|------|--------|----------| +| **Schema 校验** | blackboard.py CLI 写入时校验 JSON Schema | 强(不符合返回明确错误) | 结构化操作(handoff / output / decide / observe) | +| **Skill 引导** | Agent Skill 中的行为规范文本 | 弱(可看可不看) | 非结构化操作(普通评论、讨论) | +| **L1 截取** | Daemon 构建 L1 时自动截取 | 代码层面,Agent 无感 | 传递优化 | + +**为什么这是 AI Native**: +1. Schema 是可执行文档——Agent 不需要读 Skill 就能知道格式要求(CLI 错误信息会告诉它缺了什么) +2. 错误信息是建设性的——"Handoff must include 'completed' field" 让 Agent 知道该补什么 +3. 约束的是结构,不是内容——不限制写多长,只限制必须包含哪些字段 +4. Agent 可以自主决定深度——可选字段可以不写 +5. 和 OpenAI Agent SDK 的 handoff `input_type` 同理——Pydantic schema 校验交接数据 + +**Schema 定义**(`schemas/` 目录): + +```json +// schemas/handoff.schema.json +{ + "type": "object", + "required": ["completed", "artifacts"], + "properties": { + "completed": { "type": "string", "description": "完成了什么" }, + "artifacts": { + "type": "array", + "items": { "type": "string" }, + "description": "产出物路径列表" + }, + "remaining": { "type": "string", "description": "未完成事项(可选)" }, + "next_steps": { "type": "string", "description": "对接手者的建议(可选)" } + } +} +``` + +| 操作 | Schema 文件 | 必填字段 | 校验内容 | +|------|-----------|---------|----------| +| `--handoff` | handoff.schema.json | completed + artifacts | 结构完整,artifacts 路径存在 | +| `--output` | output.schema.json | summary + content_path | summary 非空,路径存在 | +| `--decide` | decide.schema.json | decision + rationale | 两个字段都非空 | +| `--observe` | observe.schema.json | severity + body | severity 在枚举内 | +| `--comment`(普通) | 无 | body | 无 Schema 校验,纯 Skill 引导 | + +**Agent 使用方式**: +```bash +# 结构化操作:CLI 校验 Schema +blackboard.py comment --task task-001 --author zhangfei-dev \ + --handoff '{"completed": "分批加载实现", "artifacts": ["task-001/output.md"], "remaining": "止损逻辑"}' +# 校验失败 → 返回具体错误:"Handoff must include 'completed' field" +# 校验通过 → 写入 comments 表,body 自动格式化为结构化文本 + +# 普通评论:无 Schema 校验 +blackboard.py comment --task task-001 --author zhangfei-dev \ + --body "@赵云 task-002 需要分钟线数据" +``` + +**落地到 schema(存储层)**: +- `outputs` 表:`content_path` + `summary`,不存文件内容 +- `comments` 表:`body` 存完整内容(不截断),handoff 类型自动格式化 +- `decisions` 表:`decision` + `rationale` 是结构化文本 +- `observations` 表:`body` 是风险描述 + +Agent 获取信息的分层策略(L1/L2/L3)详见 §4.4,对应 Opal-Bridge Fidelity 三档。 ---