Merged
docs: 明确知识仓与技能仓的内容边界 #134
汪超Add on 19 days ago
docs: 明确知识仓与技能仓的内容边界 #134
Merged
Total: 3 files changed+76-0
| @@ -105,6 +105,8 @@ Operator 卡按 `operators/<aclnn|direct>/<cv|math|nn|transformer>/<category>/<o | |||
| 105 | 105 | ||
| 106 | 设计取舍见[设计原则](docs/design_principles.md)；常见任务见[形成可追溯回答](recipes/answer_with_evidence.md)、[贡献知识](recipes/contribute_knowledge.md)、[查询 API](recipes/api_search.md)和[使用知识库进行算子开发](recipes/operator_development.md)。 | 106 | 设计取舍见[设计原则](docs/design_principles.md)；常见任务见[形成可追溯回答](recipes/answer_with_evidence.md)、[贡献知识](recipes/contribute_knowledge.md)、[查询 API](recipes/api_search.md)和[使用知识库进行算子开发](recipes/operator_development.md)。 |
| 107 | 107 | ||
| 108 | +知识库纳入 CANN 领域的概念与机制、API、硬件与平台知识、设计与优化方法，以及可复用的调试和故障处置经验，详见[知识纳入范围](docs/knowledge_and_skills_boundary.md#什么内容放到知识库仓)。用户可以将本仓作为个人 Skill 的知识来源，通过 `knowledge-query` 检索并引用相关知识卡。 | ||
| 109 | + | ||
J | |||
| 108 | ## 贡献和检查 | 110 | ## 贡献和检查 |
| 109 | 111 | ||
| 110 | 贡献前阅读 [CONTRIBUTING.md](CONTRIBUTING.md)，按贡献类型准备材料： | 112 | 贡献前阅读 [CONTRIBUTING.md](CONTRIBUTING.md)，按贡献类型准备材料： |
| @@ -0,0 +1,59 @@ | |||
| 1 | +# cannbot-knowledge 与 cannbot-skills 的内容边界 | ||
| 2 | + | ||
| 3 | +**技能仓保存 Agent 执行任务的指令、流程和工具；知识库仓保存 CANN 技术资料、技术方法和工程经验。** | ||
| 4 | + | ||
| 5 | +例如，“让 Agent 收集输入、完成 Tiling 设计、生成代码并运行测试”属于技能仓；“如何计算 Tiling 参数、为什么这样切分、什么情况下适用”属于知识库仓。 | ||
| 6 | + | ||
| 7 | +## 什么内容放到技能仓 | ||
| 8 | + | ||
| 9 | +放到 `cannbot-skills` 的内容，用于规定 **Agent 接到任务后要执行哪些动作，以及怎样使用配套工具完成交付**。 | ||
| 10 | + | ||
| 11 | +| 内容类型 | 具体内容 | | ||
| 12 | +|---|---| | ||
| 13 | +| 任务定义 | Skill 在什么情况下触发，需要用户提供什么输入，最终交付什么结果 | | ||
| 14 | +| 执行流程 | 先收集哪些信息，再执行哪些步骤，何时调用工具，失败后重试、回退还是停止 | | ||
| 15 | +| 工具与脚本 | 环境检查、代码生成、编译运行、日志采集、性能采集等任务的自动化脚本与封装 | | ||
| 16 | +| 工程模板 | 用于生成项目的目录骨架、构建文件、测试框架、Runner 和报告模板 | | ||
| 17 | +| 配套使用说明 | 本 Skill 自带脚本的参数与返回值、模板如何填写、生成文件放在哪里、如何判断流程是否完成 | | ||
| 18 | +| Skill 测试 | 验证 Skill 的流程、脚本、模板和异常处理是否符合约定的测试 | | ||
| 19 | + | ||
| 20 | +这些内容随 Skill 的实现一起维护。例如，采集脚本增加一个参数时，对应的调用说明也应在技能仓中修改。 | ||
| 21 | + | ||
| 22 | +## 什么内容放到知识库仓 | ||
| 23 | + | ||
| 24 | +放到 `cannbot-knowledge/knowledge/` 的内容，用于说明 **CANN 技术是什么、如何使用、有哪些约束，以及工程问题为什么发生、怎样解决**。 | ||
| 25 | + | ||
| 26 | +| 内容类型 | 具体内容 | | ||
| 27 | +|---|---| | ||
| 28 | +| 概念与机制 | 编程模型、存储层次、执行与同步机制、不同 DSL 的差异 | | ||
| 29 | +| API 知识 | 接口语义、参数含义与单位、调用前提、限制、支持的平台和版本 | | ||
| 30 | +| 硬件与平台知识 | 芯片型号与架构的对应关系、硬件能力、资源规格及平台差异 | | ||
| 31 | +| 设计与实现方法 | 算法原理、Tiling 方法、内存规划、边界处理、算子实现思路及其适用条件 | | ||
| 32 | +| 优化经验 | 指标含义、瓶颈判断依据、优化原理、收益条件和失效边界 | | ||
| 33 | +| 调试与故障经验 | 错误现象、诊断信号、根因、修复方法、复现条件和验证结果 | | ||
| 34 | +| 技术教程与示例 | 解释技术用法、算法或机制的教程和最小代码示例 | | ||
| 35 | + | ||
| 36 | +这些内容应说明来源、适用条件和验证依据。即使一项技术知识目前只被一个 Skill 使用，它仍属于知识库；被 Skill 引用不会改变内容的归属。 | ||
| 37 | + | ||
| 38 | +知识库自身用于摄入、检索、校验知识的 Skill、脚本和治理规则，作为知识库的配套设施留在本仓。 | ||
| 39 | + | ||
| 40 | +## 同一主题怎样区分 | ||
| 41 | + | ||
| 42 | +| 主题 | 放到技能仓 | 放到知识库仓 | | ||
| 43 | +|---|---|---| | ||
| 44 | +| API 使用 | 指示 Agent 在哪个步骤查接口、核对哪些条件，再继续生成代码 | API 的功能、参数语义、使用限制和平台支持情况 | | ||
| 45 | +| Tiling 设计 | 要求 Agent 收集哪些输入、输出什么设计文档、随后执行哪些生成与验证步骤 | 切分策略、参数计算公式、Buffer 规划方法及适用条件 | | ||
| 46 | +| 环境检查 | 执行哪些检查脚本、怎样汇总结果、检查失败后如何处理 | 平台识别依据、版本兼容关系及相关技术限制 | | ||
| 47 | +| 性能分析 | 怎样调用采集脚本、整理数据并生成报告 | 性能指标的含义、瓶颈判定依据、优化机制及适用范围 | | ||
| 48 | +| 故障排查 | 怎样收集日志、调用诊断工具、组织复测并交付报告 | 某类错误的根因、诊断证据、修复条件和验证方法 | | ||
| 49 | +| 代码材料 | 可以直接填充并生成工程的代码模板 | 用于解释算法、API 或优化机制的最小示例 | | ||
| 50 | + | ||
| 51 | +**技术方法和故障处置知识可以包含操作步骤。** 例如，“某类错误应检查哪些信号、怎样判断根因、如何修复”是知识库内容；“Agent 用哪个脚本采集这些信号、把结果写到哪个文件、如何组织后续动作”是 Skill 内容。 | ||
| 52 | + | ||
| 53 | +## Skill 的 references 放什么 | ||
| 54 | + | ||
| 55 | +`references/` 中保留执行当前 Skill 所需的详细说明，例如脚本用法、输入输出格式、模板填充规则、任务步骤和异常处理。 | ||
| 56 | + | ||
| 57 | +其中讲解 API、硬件规格、算法、Tiling、优化原理或故障案例的正文，应放到知识库。Skill 可以保留简短提示和知识卡链接，完整技术内容在知识库中维护。 | ||
| 58 | + | ||
| 59 | +一份参考文档同时包含两类内容时，按章节拆分。例如，性能采集脚本的调用说明留在 Skill 的 `references/`，性能指标定义和瓶颈分析方法放到知识库。 | ||
| @@ -0,0 +1,15 @@ | |||
| 1 | +# 2026-10-19 | ||
| 2 | + | ||
| 3 | +## [11:46] docs | 说明知识仓与技能仓的内容归属 | ||
| 4 | + | ||
| 5 | +### Summary | ||
| 6 | + | ||
| 7 | +新增[知识仓与技能仓的内容边界说明](../docs/knowledge_and_skills_boundary.md)，列出两个仓分别承载的内容类型，并在根 README 增加导航入口。 | ||
| 8 | + | ||
| 9 | +### Details | ||
| 10 | + | ||
| 11 | +- 明确技能仓保存 Agent 的任务指令、执行流程、工具脚本、工程模板及配套说明；知识库保存 CANN 技术资料、技术方法和工程经验。 | ||
| 12 | +- 通过 API、Tiling、环境检查、性能分析、故障排查和代码材料的对照说明归属；明确 Skill `references/` 中执行说明保留在技能仓，技术正文进入知识库，混合内容按章节拆分。 | ||
| 13 | +- 初版文档五项定向回归通过；精简后再次完成文档结构、本地链接、README 导航及空白检查，均通过。 | ||
| 14 | +- 提交前运行 `bash check.sh`：全库 Lint（8,355 张卡，P0/P1/P2 均为 0）、669 个目录索引检查、检索索引构建与完整验证通过；检索质量门禁因 MRR=0.443 未达到 >0.45 的要求而失败，脚本中后续检查未执行。 | ||
| 15 | +- 已确认知识正文、检索与治理实现、评测用例和检查脚本均与远端 `add_boundary` 一致，本次只修改说明文档、README 导航和本条日志。 | ||
建议不提cannbot-skill，只提knowledge仓的纳入范围，可对接到用户个人的skill。