auto-sync: 2026-05-15 13:51:37

2026-05-15 13:51:37 +08:00
parent 9e7d52240a
commit 108ddb2117
1 changed files with 64 additions and 6 deletions
@@ -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 三档。

 ---