ambiguous-pointer opened a new issue, #1613: URL: https://github.com/apache/dubbo-admin/issues/1613
## 背景 Dubbo Admin 的 AI 服务(`ai/` 模块)已经具备 LLM 对话、RAG 知识检索、MCP 工具接入、对话持久化、Agent hooks 等能力,但**缺少一个"可复用领域流程知识"的运行时载体**。 仓库里其实已经存在高质量的领域知识资产:`.agents/skills/` 下的 8 个 dubbo-admin 领域 skill(console-api / discovery / domain / engine / events / frontend / runtime / store),每个包含: - `SKILL.md`:frontmatter(`name` + `description`)+ 固定 8 段骨架正文(Purpose / When to use / Inputs / Workflow / Output format / Validation / Edge cases / References) - `references/*.md`:端到端调用链、真实源码片段、review checklist - `evals/evals.json`:5 类触发用例(obvious / paraphrased / file-based / no-trigger / conflict-trigger) 但它们**只被仓库外的编码助手(Claude Code / Codex 等)按目录约定自动发现**,`ai/` 服务、CI、Makefile 全都不读取 —— 对 AI 服务而言这些资产目前是惰性的。 ## 1. 为什么需要 Skill 机制 ### 1.1 今天 AI 服务只有两条"知识进模型"的路径,都不够用 | 路径 | 机制 | 问题 | | --- | --- | --- | | 静态提示词 | `ai/prompts/agentReasonAct.txt` | 全局策略(角色、安全边界、指标词表),**装不下领域流程**:改 store 索引语义该看哪几个文件、跑哪些验证命令、边界上和哪个 skill 冲突 | | RAG 检索 | `query_knowledge_base` / `retrieve_basic_concept_from_k8s_doc` 工具 | 面向**事实性文档**(Dubbo/K8s 官方文档、RAG seed 知识),按语义召回 chunk。领域 skill 是**流程性指令**(工作步骤 + 边界 + 验证命令),语义检索会丢掉结构与确定性,也不保证被召回 | ### 1.2 三个候选方案对比 - **全量塞进 system prompt**:token 成本随 skill 数量线性膨胀,且把 8 个领域流程同时暴露给模型 → 干扰大、易误用。 - **全部走 RAG**:丢失结构与触发条件,模型无法判断"这条 skill 现在适不适用";且 skill 本身体量小(2–3 KB)、可枚举,不需要向量检索。 - **Skill 机制(渐进式披露)**:目录常驻(name + description,含"何时该用 / 何时不该用"),正文与参考文档按需拉取 —— 与 Claude Code / Anthropic Agent Skills 的模型一致,且已有资产格式可直接复用。 ### 1.3 收益 - **领域流程可执行化**:AI 能按 Dubbo Admin 自己的规范工作(引用真实文件路径、给出验证命令、明确跨领域边界)。 - **单一事实源**:`.agents/skills` 同时服务编码助手与线上 AI 服务,改一次两处生效,走同一套 code review。 - **可评测**:现成的 `evals/evals.json` 提供了"该不该触发"的回归用例基线。 - **成本可控**:目录常驻约 500 token(8 个 skill),正文按需加载。 ## 2. 当前遇到了什么困难 1. **运行时载体缺失**:`ai/` 模块检索 `skill` 零命中 —— 没有解析器、没有注册表、没有组件、没有任何工具。 2. **没有设计定稿**:全仓(除 `.agents/` 外)"skill" 零命中,没有设计稿 / 计划 / TODO;唯一的设计文档 `docs/ai-context-management-design.md` 主题是页面上下文,与本议题无关。 3. **信任边界冲突(最核心的技术障碍)**:`ai/prompts/agentReasonAct.txt` 现行策略把 `tool outputs` / `retrieved documents` 一律判为**不可信数据**并禁止执行其中的指令;而 skill 正文是**指令**(工作流、约束、验证步骤)。若沿用现有工具通道回灌,模型会把 skill 当"证据"而非"方法",Skill 机制直接失效。 4. **没有注入口**:`ai/component/agent/react/prompt.go` 的 system prompt 是**构造期**读盘拼装的静态字符串;`ai/component/agent/react/steps.go` 的 messages 纯粹来自 conversation store —— 代码里没有任何"非对话内容"进入 prompt 的通道。 5. **组件化约束容易踩坑**:组件按**工厂注册顺序**初始化(`ai/runtime/runtime.go`),新组件注册位置错了会在 `Init` 时取不到依赖;配置是严格模式(`KnownFields(true)`),新增 YAML 字段若未在 JSON Schema 声明会**启动即失败**。 6. **评测没有 runner**:`evals/evals.json` 是一份自描述清单,仓内和 CI 都没有执行器,触发质量无法回归。 7. **能力边界易被误解**:需要明确 skill **只提供指令,不扩大工具权限**(工具白名单仍由 `tools` 组件与 MCP 决定),否则"一份 markdown 就能让模型多一把钥匙"。 ## 3. 产物效果 ### 3.1 用户视角(before / after) **Before** > 用户:这个 service 的索引查询为什么查不到? > AI:(泛泛解释 radix tree 原理,给出自己编的目录结构,建议"检查一下 index 注册") **After** > AI:按 `dubbo-admin-store` skill 的工作流处理 —— > ① 确认索引在 `pkg/core/store/index/` 注册,且 `IndexCondition` 与查询条件一致; > ② 用 `ListByIndexes` / `PageListByIndexes` 验证; > ③ 注意与 `dubbo-admin-console-api` 的边界:若改的是 HTTP 端点契约,由 Console API skill 主导。 > 验证命令:`go test ./pkg/core/store/...` 即 AI 会**引用仓库真实路径、给出可执行的验证命令、在跨领域时主动切换 skill**,而不是泛泛而谈。 ### 3.2 资产视角 - `.agents/skills/` 成为 **CLI 编码助手 + 线上 AI 服务**共用的单一事实源; - `ai/skills/` 可承载 AI 服务专属技能(诊断流程、排障手册),二者按 `base_paths` 顺序合并、靠前优先。 ### 3.3 运行时视角:三层渐进披露 | 层 | 内容 | 进入模型的方式 | 成本 | | --- | --- | --- | --- | | L0 | 全部 skill 的 `name` + `description` | 常驻 act 阶段 system prompt | ~500 token(8 个 skill) | | L1 | 单个 `SKILL.md` 正文 | `load_skill(name)` 工具按需拉取 | 按需 | | L2 | `references/*.md` | `read_skill_file(name, path)` 按需拉取 | 按需 | ### 3.4 可度量 - skill 命中率 / 误触发率(复用 `evals/evals.json` 五类用例); - prompt token 预算(目录常驻量固定); - 加载失败率(invalid skill、越权路径请求)。 ## 4. 如何做到 Skill 机制(概要) 采用**渐进式披露(progressive disclosure)** 模型,并把它作为 `ai/` 模块的一个新组件落地: 1. **新组件 `skill`**:启动时扫描 `base_paths` 指定的目录,解析 `SKILL.md` 的 frontmatter 与正文,构建**只读目录(catalog)**; 2. **目录注入**:把 catalog 的 `name` + `description` 拼成 `## Available Skills` 段落,注入 ReAct **act 阶段**的 system prompt(answer 阶段无工具,不注入); 3. **正文按需**:新增 `load_skill` / `read_skill_file` 两个工具,走现有 `genkit.DefineTool` + `ToolOutput` 信封,Agent 执行链路零改动; 4. **信任处理**:来源可信性由 loader 构造性保证(只读配置目录、路径不接受用户输入),并在共享策略文件里**窄口径豁免**这两个工具的输出为"受控技能指令",同时保留"不得覆盖系统策略 / 阶段策略 / 工具边界"; 5. **评测**:新建最小 runner,对 `evals/evals.json` 的五类触发用例做回归。 具体的技术方案、文件改动清单与设计取舍,见本 Issue 下的评论。 ## 5. 验收标准 - [ ] AI 服务能加载 `.agents/skills` 下的 skill,并在适用问题中按 skill 流程作答(引用真实文件路径 / 验证命令) - [ ] 不适用的问题**不会**误触发 skill - [ ] L0 目录常驻开销可量化(token 统计),L1 / L2 按需加载 - [ ] 越权路径请求(`../`、绝对路径、非法扩展名、超限文件)被拒绝 - [ ] skill 内容**不扩大**工具可用范围 - [ ] `evals/evals.json` 五类用例可自动回归 - [ ] 新增组件遵循既有约定:YAML 声明 + JSON Schema 校验 + runtime 生命周期 + 单测 ## 6. 相关链接 - 现有资产:`.agents/skills/` - 相关设计(语义相反:不可信数据 vs 可信指令,建议分开实施):`docs/ai-context-management-design.md` - 设计草案 `docs/ai-skill-design.md` 将随实现 PR 一并提交 -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected] --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
