Repository navigation
spec: agent.knowledge.indexes / sources reference a namespace with no definition site in a stack #3699
Description
从 #3583 的引用完整性工作中分出来的 spec 决策项(方案文档 §5 D1,见 docs/audits/2026-07-app-metadata-reference-integrity-assessment.md)。
现状
AgentSchema.knowledge 声明了两个引用形状的字段:
packages/spec/src/ai/agent.zod.ts:37—indexes: z.array(z.string()).describe('Vector Store Indexes')(必填)- 同处
sources: z.array(z.string()).optional()
但这两个字段引用的命名空间在 stack 里没有任何定义位:
KnowledgeSourceSchema确实存在(packages/spec/src/ai/knowledge-source.zod.ts:86),但stack.zod.ts从未引用它 —— 没有knowledgeSources: []槽位。- 唯一「index」形状的声明是
VectorStoreSchema.collection(packages/spec/src/ai/embedding.zod.ts:71),只能从 KnowledgeSource 到达,而后者本身不可在 stack 中书写。
也就是说,作者写进 knowledge.indexes 的任何字符串,按构造就是不可解析的。
为什么这是决策而不是 bug
按 ADR-0049 / ADR-0078 的三分法,一个已解析的配置必须处于以下之一:强制校验、标注 [EXPERIMENTAL — not enforced]、或优雅降级的真可选。当前状态是被明确禁止的第四态:可解析、未标注、静默失效。
这也是为什么 #3583 的 AI 引用规则(方案里的 R7)没有写:给一个没有定义位的命名空间加校验,等于把这个缺口制度化。
两个出口
- 加定义位 —— 把
knowledgeSources接入stack.zod.ts,让indexes/sources能真正解析。之后 R7 可以连同agent.skills→stack.skills、skill.tools→stack.tools一起写。 - 标注为实验性 —— 在字段上加
[EXPERIMENTAL — not enforced],明确「现在写它是无操作」,作者就不会误以为有效。
出口 1 是 spec 变更,值得一个 ADR;出口 2 是一行 describe 改动。任一都行,现状不行。
关联
- lint: no reference-integrity or option-key validation for app metadata #3583(引用完整性审计)
- feat(lint): reference-integrity validation for object and action names (#3583) #3657 / feat(lint): page-component field bindings + non-dashboard chart bindings (#3583) #3684 / feat(lint): navigation reachability vs. granted access (#3583) #3698(已落地的规则)
- ADR-0049 / ADR-0078
Activity
os-zhuang commentedon Aug 2, 2026
裁决(维护者 2026-08-02 委托,按四轴评估:长远合理性 / 防 AI 静默犯错 / 实际业务 / 不扩边界):出口 2 —— 标注
[EXPERIMENTAL — not enforced],并把indexes从必填放宽为 optional。放宽必填是 loosening(非破坏),标注是一行 describe 改动;两者可同一 PR。
Generated by Claude Code
os-zhuang commentedon Aug 2, 2026
关闭说明:已被 #3896 超越(overtaken)。
本 issue 讨论的
agent.knowledge.indexes/sources已在 @objectstack/spec 17.0.0 的 #3896 审计收尾中整块移除(agent.zod.ts留有retiredKey墓碑 + 迁移处方,ADR-0087 conversionagent-knowledge-removed在链上;liveness 账本判dead+authorWarn)。正文列的两个出口(加定义位 / 标 EXPERIMENTAL)被第三条路——移除——实际解决:字段不存在了,"可解析但按构造不可解析"的第四态随之消失。上一条裁决评论(选出口 2)以本 issue 正文为据、未核对 main 现场,作废。维护者今日确认知识库方向暂停、非近期产品主线,与 #3896 的移除裁决一致;知识能力保留在 service 层(service-knowledge / knowledge-memory / knowledge-ragflow),那里有真实运行时消费者。将来若 agent 级知识声明回到路线图,以加法重新引入(经 ADR),不欠 v17 的债。
Generated by Claude Code