feat: 统一知识库安装与使用入口-cannbot-knowledge-AtomGit

已合并

feat: 统一知识库安装与使用入口 #32

汪超创建于 9月14日从qq_41667743/cannbot-knowledge： add_install 合入到 cann/cannbot-knowledge： master

feat: 统一知识库安装与使用入口 #32

已合并

汪超创建于 9月14日

从qq_41667743/cannbot-knowledge add_install合入到cann/cannbot-knowledge master

共 22 个文件变更+1424-376

MAGENTS.md+1-1

	@@ -71,7 +71,7 @@ Schema、Profile、Registry、Contract、Spec、Skill 或测试若互相矛盾
71	- 项目安装通过本仓安装器链接到完整 checkout，保持 Skill、相邻依赖和 `governance/contracts/` 同版本可用；配置知识根不等于支持独立复制 Skill 目录。	71	- 项目安装通过本仓安装器链接到完整 checkout，保持 Skill、相邻依赖和 `governance/contracts/` 同版本可用；配置知识根不等于支持独立复制 Skill 目录。
72	- 治理、安装、检索与 CI 回归集中于 `evals/`；Ingest 通过全库确定性命令和仓库级回归验证，trace producer 保留其专用脚本回归。按需图谱与 CI 共用 Ingest 的同一链接构图实现。	72	- 治理、安装、检索与 CI 回归集中于 `evals/`；Ingest 通过全库确定性命令和仓库级回归验证，trace producer 保留其专用脚本回归。按需图谱与 CI 共用 Ingest 的同一链接构图实现。
73	- 官方文档归档持续更新，不校验归档或内容树 SHA-256；完成标记记录来源 URL 与准备时间，刷新来源不自动更新知识卡。Git 源码继续固定到登记的 40 位 commit。	73	- 官方文档归档持续更新，不校验归档或内容树 SHA-256；完成标记记录来源 URL 与准备时间，刷新来源不自动更新知识卡。Git 源码继续固定到登记的 40 位 commit。
74	-- 安装器默认恢复登记的文档与固定版本源码，再准备 Query 索引；显式离线模式可以跳过资源获取，Query/Lint 本身不得自动联网。资源只放在 ignored 来源根，不执行上游源码或覆盖有本地修改的 checkout。	74	+- 统一安装入口是根目录 `install.sh`。远程执行时默认自动克隆或仅快进更新托管知识仓；更新已有托管仓前必须确认当前分支与请求分支一致，从已有本地知识仓执行时复用当前 checkout，不自动切换或更新当前分支。安装器按 `requirements.txt` 补齐缺失的 Python 运行依赖，随后默认恢复登记的文档归档与固定版本源码，再准备 Query 索引；显式离线模式可以跳过仓库更新和资源获取，且不要求本地 checkout 的 origin 匹配默认远端。Query/Lint 本身不得自动联网。资源只放在 ignored 来源根，不执行上游源码或覆盖有本地修改的 checkout。
75	- Skill 保存生产、查询和治理知识的工作流、工具及必要的小型参考资料；可被复用的技术事实必须写入 `knowledge/`。Ingest 按需构图只读取现有链接，不回写知识正文。	75	- Skill 保存生产、查询和治理知识的工作流、工具及必要的小型参考资料；可被复用的技术事实必须写入 `knowledge/`。Ingest 按需构图只读取现有链接，不回写知识正文。
76	- `consumer` 和 `contributor` 是安装模式，不是路径 Profile、OKF `type` 或知识分类。	76	- `consumer` 和 `contributor` 是安装模式，不是路径 Profile、OKF `type` 或知识分类。
77	- `ascendc-api-knowledge-query` 与 `knowledge-query` 一起安装，复用同一索引、平台识别和审计契约；API 头文件线索以已确认的 AscendC 包根解析，不能按知识仓根拼接或跨版本猜测。相关链接只帮助按需补齐证据，不要求遍历全部邻接卡片。	77	- `ascendc-api-knowledge-query` 与 `knowledge-query` 一起安装，复用同一索引、平台识别和审计契约；API 头文件线索以已确认的 AscendC 包根解析，不能按知识仓根拼接或跨版本猜测。相关链接只帮助按需补齐证据，不要求遍历全部邻接卡片。

MCONTRIBUTING.md+5-3

	@@ -1,6 +1,6 @@
1	# cannbot-knowledge 贡献指南	1	# cannbot-knowledge 贡献指南
2		2
3	-本文只说明贡献流程和交付要求。字段、路径与受控值的完整定义由 `governance/` 维护，Skill 的内部命令与参数由各 Skill 自身文档维护，避免在多处复制同一规则。	3	+本文只说明贡献流程和交付要求。环境安装与 `contributor` 模式见[安装与使用指南](docs/installation_and_usage.md)；字段、路径与受控值的完整定义由 `governance/` 维护，Skill 的内部命令与参数由各 Skill 自身文档维护，避免在多处复制同一规则。
4		4
5	## 1. 规则从哪里读取	5	## 1. 规则从哪里读取
6		6
	@@ -82,7 +82,9 @@ knowledge/<domain>/<technology-or-scope>/<profile>/<slug>.md
82		82
83	### 3.4 准备来源	83	### 3.4 准备来源
84		84
85	-每张卡都必须填写 `sources`。轨迹沉淀的 `Runbook` 可以使用 `sources: []`，但正文必须保留与结论强度相匹配的触发、探针、原始观测和验证信号，且不能把中间整理仓或会话轨迹伪装成权威 resource；其它非 `draft` 卡至少有一个精确 `resource`。Git 来源固定到提交，文档来源优先使用稳定版本页。仓库相对来源必须位于 Registry 登记的本地来源根目录，并由登记的官方文档归档 URL 或 Git repository/40 位 commit 获取流程恢复；不能指向未登记根目录、工作区外部或包含路径穿越。性能、精度、平台限制、默认行为和经验性结论必须有与结论强度相匹配的证据。	85	+每张卡都必须填写 `sources`。轨迹沉淀的 `Runbook` 可以使用 `sources: []`，但正文必须保留与结论强度相匹配的触发、探针、原始观测和验证信号，且不能把中间整理仓或会话轨迹伪装成权威 resource；其他非 `draft` 卡至少有一个精确 `resource`。
		86	+
		87	+Git 来源固定到提交；普通文档来源优先使用稳定版本页，Registry 登记的滚动文档归档则使用其官方归档 URL。仓库相对来源必须位于 Registry 登记的本地来源根目录，并由登记的文档归档 URL 或 Git repository/40 位 commit 获取流程恢复；不能指向未登记根目录、工作区外部或包含路径穿越。性能、精度、平台限制、默认行为和经验性结论必须有与结论强度相匹配的证据。
86		88
87	搜索摘要、PR 标题、聊天记录或模型记忆不能单独作为技术来源。来源角色、固定格式和人工审阅要求见 [Frontmatter 与证据](governance/specs/frontmatter.md)。	89	搜索摘要、PR 标题、聊天记录或模型记忆不能单独作为技术来源。来源角色、固定格式和人工审阅要求见 [Frontmatter 与证据](governance/specs/frontmatter.md)。
88		90
	@@ -121,7 +123,7 @@ knowledge/<domain>/<technology-or-scope>/<profile>/<slug>.md
121	- 新增、删除或移动卡片时，同步受影响的每一级 `index.md`；	123	- 新增、删除或移动卡片时，同步受影响的每一级 `index.md`；
122	- 卡片移动时在同一变更中更新正文链接；Concept 与索引链接必须留在 `knowledge/` Bundle 内；知识卡可额外链接登记的固定提交本地源码文件作为证据导航，不生成源码 Concept；	124	- 卡片移动时在同一变更中更新正文链接；Concept 与索引链接必须留在 `knowledge/` Bundle 内；知识卡可额外链接登记的固定提交本地源码文件作为证据导航，不生成源码 Concept；
123	- 实质知识或治理变更记录到当天 `logs/`，纯排版和错别字修复不记录；	125	- 实质知识或治理变更记录到当天 `logs/`，纯排版和错别字修复不记录；
124	-- 图谱按需从知识卡之间的普通 Markdown 链接生成，包括 API 与算子卡片的关联。日常入库不构图、不做全库关系判定，不维护专用区块；没有链接的卡片也可入库。Index 仅提供导航，固定源码仅用于来源；图谱产物保存在 ignored 的 `artifacts/graphs/`。	126	+- 图谱按需从知识卡之间的普通 Markdown 链接生成，包括 API 与算子卡片的关联。日常入库不构图、不做全库关系判定，不维护专用区块；没有链接的卡片也可入库。Index 仅提供导航，固定源码仅用于来源；图谱产物保存在 Git 忽略的 `artifacts/graphs/`。
125		127
126	### 3.8 知识提交检查	128	### 3.8 知识提交检查
127		129

MREADME.md+14-58

	@@ -11,7 +11,7 @@ CANNBot 通过本仓提供的 Skill 生产、检索和检查这些知识，从
11		11
12	## 设计参考	12	## 设计参考
13		13
14	-本仓知识正文的文件化设计参考 Google 的 [Open Knowledge Format（OKF）v0.2](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/fe3268a70e8ca5110a43a8f1dfdf6d1a458cf79f/okf/SPEC.md)：知识使用带 YAML Frontmatter 的 Markdown 表达，通过目录和 `index.md` 渐进浏览，通过普通 Markdown 链接形成可重建关系，并使用 Git 分发和审计。	14	+本仓知识正文的文件化设计参考 Google 的 [Open Knowledge Format（OKF）v0.2](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/fe3268a70e8ca5110a43a8f1dfdf6d1a458cf79f/okf/SPEC.md)。知识使用带 YAML Frontmatter 的 Markdown 表达，通过目录和 `index.md` 渐进浏览，通过普通 Markdown 链接形成可重建关系，并使用 Git 分发和审计。
15		15
16	`knowledge/` 是本仓唯一且符合 OKF v0.2 的 Knowledge Bundle 根目录，其下所有卡片共享同一个 Concept ID 命名空间。`common/`、`ops/` 等只是 Bundle 内的分类，不是独立 Bundle；仓库根目录的 Skill、治理、测试和日志设施不属于 Bundle。详细边界见 [OKF Bundle 与 CANNBot Profile](governance/specs/okf.md)。	16	`knowledge/` 是本仓唯一且符合 OKF v0.2 的 Knowledge Bundle 根目录，其下所有卡片共享同一个 Concept ID 命名空间。`common/`、`ops/` 等只是 Bundle 内的分类，不是独立 Bundle；仓库根目录的 Skill、治理、测试和日志设施不属于 Bundle。详细边界见 [OKF Bundle 与 CANNBot Profile](governance/specs/okf.md)。
17		17
	@@ -28,7 +28,7 @@ CANNBot 通过本仓提供的 Skill 生产、检索和检查这些知识，从
28	- 11 张 Triton Example 卡；	28	- 11 张 Triton Example 卡；
29	- Ascend C API/Guide 来源指向 Registry 登记的 `cann-docs-raw/` 文档归档，官方归档持续更新，恢复时不校验预登记的归档或内容树 SHA-256；模型 Guide 来源固定到托管仓 40 位 Commit 和具体文件，Operator 来源固定到 CANN 官方 Git 仓 40 位 Commit 和具体文件。	29	- Ascend C API/Guide 来源指向 Registry 登记的 `cann-docs-raw/` 文档归档，官方归档持续更新，恢复时不校验预登记的归档或内容树 SHA-256；模型 Guide 来源固定到托管仓 40 位 Commit 和具体文件，Operator 来源固定到 CANN 官方 Git 仓 40 位 Commit 和具体文件。
30		30
31	-上述数量是当前版本快照。Registry 中注册的所有 domain 根目录始终保留；`ops` 和 `model` 额外预建已注册 route，其他领域的下一层路径由领域维护者在首批真实知识落库时创建。只有 `index.md` 的结构入口不算正式知识卡，也不会出现在 Query 的实际覆盖统计中。“存在目录”不表示“已有知识”，实时数量以 Query `discover` 为准。	31	+上述数量是当前版本快照。Registry 中注册的所有 domain 根目录始终保留；`ops` 和 `model` 额外预建已注册 route，其他领域的下一层路径随首批真实知识创建。只有 `index.md` 的结构入口不算正式知识卡，也不会出现在 Query 的覆盖统计中。“存在目录”不表示“已有知识”，实时数量以 Query 返回的实际覆盖为准。
32		32
33	本地来源不提交到 Git。需要核对卡片证据时，在仓库根执行：	33	本地来源不提交到 Git。需要核对卡片证据时，在仓库根执行：
34		34
	@@ -36,13 +36,13 @@ CANNBot 通过本仓提供的 Skill 生产、检索和检查这些知识，从
36	bash get_resources.sh	36	bash get_resources.sh
37	```	37	```
38		38
39	-脚本默认恢复文档及 `ops-nn`、`ops-math`、`ops-transformer`、`ops-cv` 源码；也可用 `--docs` 或 `--code` 单独恢复。源码按 Registry 中的固定 40 位提交统一放在 `cann-ops-raw/ascendc/<仓库名>/<commit>/`，当前每仓只登记一个提交，Direct Invoke 与 ACLNN 共用同仓基线；复用前校验提交、来源和工作区，拒绝覆盖本地修改。Operator 的本地 `sources` 路径相对于知识仓根，本地化只改写可用文件，对缺失来源明确报告，不自动切换版本。安装器默认准备这些资源；显式离线安装可传 `--skip-resources`。源码与归档均不提交。	39	+脚本默认恢复滚动更新的官方文档归档，以及 `ops-nn`、`ops-math`、`ops-transformer`、`ops-cv` 的固定提交源码；也可用 `--docs` 或 `--code` 只恢复一类资源。文档缓存默认复用，需要获取当前归档时使用 `bash get_resources.sh --docs --refresh`；源码复用前会校验提交、来源和工作区。两类资源都保持 Git 忽略，脚本不会覆盖不完整目录或带本地修改的源码。
40		40
41	-API 卡片通过普通 Markdown 链接引用算子知识。需要发现新引用时，可按需生成基于固定源码调用或正文示例的建议；建议区分证据来源和扫描范围，不证明运行时可达性，也不限制卡片已有链接的数量。	41	+Operator 的本地 `sources` 使用相对于知识仓根的固定提交路径，缺失来源不会被自动替换成其他版本。官方 API/Guide 只为包含独立技术事实的来源页建卡，导航页由逐层 `index.md` 承载；“产品支持情况”转换为 Frontmatter `platforms`，其余保留正文按受控规则同步。
42		42
43	-图谱按需读取卡片之间的现有链接；API 引用建议单独按需执行，不作为知识入库或 CI 构图的前置步骤。	43	+完整来源和转换约束见 [Frontmatter 与证据](governance/specs/frontmatter.md)与 [Schema、Registry 与 Contract](governance/specs/schemas.md)。
44		44
45	-文档恢复时，脚本从 Registry 登记的官方 URL 下载到 `cann-docs-raw/`，不校验归档或内容树 SHA-256；已完成的本地缓存默认复用，可通过 `bash get_resources.sh --docs --refresh` 获取当前文档。完成标记记录来源 URL 和本地准备时间；未完成的目录不会被覆盖。获取阶段只修复已知文件中的特定代码 token 链接，不固定修复次数。官方 API/Guide 只为含独立技术事实的来源页建卡，README、发布占位、纯链接目录和接口清单由逐层 `index.md` 统一导航；保留页的“产品支持情况”先写入 Frontmatter `platforms` 再从正文省略，其余正文保持完整并修正失效链接，可通过普通 Markdown 链接导航到使用相关 API 的算子知识。	45	+知识卡之间通过普通 Markdown 链接形成关系，图谱按需从这些链接生成。API 引用建议可以单独扫描固定源码，但建议不证明运行时可达性，也不会自动改写知识卡或成为入库前置步骤。
46		46
47	## 这个仓库如何工作	47	## 这个仓库如何工作
48		48
	@@ -50,7 +50,7 @@ API 卡片通过普通 Markdown 链接引用算子知识。需要发现新引用
50	官方文档 / 固定版本源码 / 可复现实验	50	官方文档 / 固定版本源码 / 可复现实验
51	│	51	│
52	▼	52	▼
53	- knowledge-ingest / trace / VV / CV	53	+ Ingest 与专用 producer
54	│	54	│
55	▼	55	▼
56	Markdown 知识卡	56	Markdown 知识卡
	@@ -69,7 +69,7 @@ API 卡片通过普通 Markdown 链接引用算子知识。需要发现新引用
69	\|---\|---\|---\|	69	\|---\|---\|---\|
70	\| `knowledge-query` \| 查看实际知识覆盖，检索知识卡，并可保存不可覆盖的审计 receipt \| 除指定 receipt 外只读 \|	70	\| `knowledge-query` \| 查看实际知识覆盖，检索知识卡，并可保存不可覆盖的审计 receipt \| 除指定 receipt 外只读 \|
71	\| `ascendc-api-knowledge-query` \| 复用 Query 按硬件平台检索 Ascend C API，阅读全文并按需追踪相关卡片和本地 CANN 头文件 \| 否 \|	71	\| `ascendc-api-knowledge-query` \| 复用 Query 按硬件平台检索 Ascend C API，阅读全文并按需追踪相关卡片和本地 CANN 头文件 \| 否 \|
72	-\| `knowledge-ingest` \| 统一路由新来源、增量、版本升级和通用建卡，支持按需链接图谱 \| 创建候选卡；构图只读正文，产物始终 ignored \|	72	+\| `knowledge-ingest` \| 统一路由新来源、增量、版本升级和通用建卡，支持按需链接图谱 \| 创建候选卡；构图只读正文，产物始终由 Git 忽略 \|
73	\| `knowledge-lint` \| 检查目录、Frontmatter、来源、正文、导航和日志；整理 Issue 材料 \| 否 \|	73	\| `knowledge-lint` \| 检查目录、Frontmatter、来源、正文、导航和日志；整理 Issue 材料 \| 否 \|
74	\| `ops-knowledge-trace-ingest` \| 从算子开发 trace 蒸馏 Runbook，并按当前 Schema、导航、Lint 和检索门禁收口 \| 仓内使用；只写经审查的 Runbook、导航和日志 \|	74	\| `ops-knowledge-trace-ingest` \| 从算子开发 trace 蒸馏 Runbook，并按当前 Schema、导航、Lint 和检索门禁收口 \| 仓内使用；只写经审查的 Runbook、导航和日志 \|
75	\| `ops-knowledge-vv-ingest` \| 从固定版本源码提取不含可达 Cube/AIC 或 MIX_CV 节点的完整 Operator 卡 \| 只写任务指定的最终卡 \|	75	\| `ops-knowledge-vv-ingest` \| 从固定版本源码提取不含可达 Cube/AIC 或 MIX_CV 节点的完整 Operator 卡 \| 只写任务指定的最终卡 \|
	@@ -113,64 +113,20 @@ Operator 卡按 `operators/<aclnn\|direct>/<cv\|math\|nn\|transformer>/<category>/<o
113	\| `governance/specs/` \| 对治理规则的完整文字说明 \|	113	\| `governance/specs/` \| 对治理规则的完整文字说明 \|
114	\| `governance/contracts/` \| Ingest、Query、Lint 和图谱共同使用的校验实现 \|	114	\| `governance/contracts/` \| Ingest、Query、Lint 和图谱共同使用的校验实现 \|
115	\| `.agents/skills/` \| 三项基础 Skill、Ascend C API 专用消费流程、仓内 trace producer 与两项源码级 Operator producer 的规范源 \|	115	\| `.agents/skills/` \| 三项基础 Skill、Ascend C API 专用消费流程、仓内 trace producer 与两项源码级 Operator producer 的规范源 \|
116	-\| `docs/` \| 知识库设计原则和用户指南 \|	116	+\| `docs/` \| 知识库设计原则、安装与使用指南 \|
117	\| `recipes/` \| 面向具体任务的知识库最佳实践 \|	117	\| `recipes/` \| 面向具体任务的知识库最佳实践 \|
118	\| `evals/` \| 检索、治理、文档和安装回归 \|	118	\| `evals/` \| 检索、治理、文档和安装回归 \|
119	\| `OAT.xml` \| GitCode 开源扫描使用的 CANN 2.0 许可策略和 matcher \|	119	\| `OAT.xml` \| GitCode 开源扫描使用的 CANN 2.0 许可策略和 matcher \|
120	-\| `init.sh` \| 把 Skill 安装到目标项目 \|	120	+\| `install.sh` \| 自动取得知识仓、补齐运行依赖、恢复资源、准备索引并把 Skill 安装到目标项目 \|
121	\| `check.sh` \| 运行仓库完整质量检查 \|	121	\| `check.sh` \| 运行仓库完整质量检查 \|
122	\| `artifacts/` \| 本地生成且可重建的产物，默认不提交 \|	122	\| `artifacts/` \| 本地生成且可重建的产物，默认不提交 \|
123	\| `logs/` \| 已实施的知识和治理变更记录 \|	123	\| `logs/` \| 已实施的知识和治理变更记录 \|
124		124
125	-## 使用知识库	125	+## 安装与使用
126		126
127	-安装 Skill 后，可以直接向 Agent 描述任务：	127	+安装和使用方法见[安装与使用指南](docs/installation_and_usage.md)。
128		128
129	-- “使用 `knowledge-query` 查看当前知识库包含哪些内容。”	129	+设计取舍见[设计原则](docs/design_principles.md)；常见任务见[形成可追溯回答](recipes/answer_with_evidence.md)、[贡献知识](recipes/contribute_knowledge.md)、[查询 API](recipes/api_search.md)和[使用知识库进行算子开发](recipes/operator_development.md)。
130	-- “使用 `ascendc-api-knowledge-query` 查询目标硬件上的 Ascend C API；必要时沿相关卡片和当前 CANN 包头文件核验。”
131	-- “使用 `knowledge-query` 检索目标平台上的某项 CANN API；精确 API 名零命中时独立补搜未定位 draft，仍无结果再明确报告当前知识缺口。”
132	-- “使用 `knowledge-ingest` 把这份固定版本文档整理成候选知识卡。”
133	-- “使用 `ops-knowledge-vv-ingest` 从固定源码提取非 Cube Operator 卡。”
134	-- “使用 `ops-knowledge-cv-ingest` 从固定源码提取含 Cube/MIX_CV 的 Operator 卡。”
135	-- “使用 `knowledge-lint` 检查本次知识修改。”
136	-
137	-查询结果只是候选知识。形成技术结论前，Agent 仍需读取知识卡正文，核对适用平台、版本、信任层级和来源。
138	-
139	-进一步了解知识库的设计和使用方式：
140	-
141	-- [设计原则](docs/design_principles.md)：知识根、治理分层、范围隔离、证据和失败关闭等关键取舍。
142	-- [用户指南](docs/user_guide.md)：consumer 与 contributor 的使用方式，以及如何理解查询结果。
143	-- [形成可追溯回答](recipes/answer_with_evidence.md)、[贡献知识](recipes/contribute_knowledge.md)和[使用知识库查询 API](recipes/api_search.md)：面向具体任务的场景化实践。
144	-- [使用知识库进行算子开发](recipes/operator_development.md)：把知识检索、实现与验证串联到算子开发任务中。
145	-
146	-## 环境准备
147	-
148	-要求 Python 3.10 或更高版本。只使用知识库时安装运行依赖：
149	-
150	-```bash
151	-python3 -m pip install -r requirements.txt
152	-```
153	-
154	-参与知识、治理或 Skill 贡献时安装开发依赖即可；它已经包含运行依赖：
155	-
156	-```bash
157	-python3 -m pip install -r requirements-dev.txt
158	-```
159	-
160	-## 安装到项目
161	-
162	-使用知识仓根目录的 `init.sh` 时，目标项目必须已经存在。`consumer` 安装 `knowledge-query` 和 `ascendc-api-knowledge-query`；`contributor` 安装三项基础 Skill、`ascendc-api-knowledge-query` 和两项 Operator producer，共6项。仓内专用的 `ops-knowledge-trace-ingest` 不安装到业务项目：
163	-
164	-```bash
165	-bash init.sh claude /path/to/project consumer
166	-bash init.sh agents /path/to/project contributor
167	-```
168	-
169	-支持 `agents`、`codex`、`claude`、`opencode`、`trae`、`cursor` 和 `copilot`。安装器始终在目标项目的 `.agents/skills/` 创建规范链接，再按客户端创建适配链接；同时验证或构建只读检索索引、把知识根和安装 profile 写入项目级 `.cannbot/knowledge.env`，并向 `AGENTS.md` 或 `CLAUDE.md` 注入可卸载的托管使用入口。文件及父目录冲突、父目录符号链接越界和托管 marker 异常都在写入前失败，不复制知识正文，也不修改用户全局配置。
170	-
171	-只刷新或移除托管提示词时使用 `--prompt-action reinstall\|uninstall`；这两个操作不增删 Skill 链接，也不更新安装 profile 配置。`reinstall` 默认复用 `.cannbot/knowledge.env` 中记录的 profile；旧安装没有该字段时根据已安装的基础贡献 Skill 推导。普通安装补齐所选模式的 Skill 并更新配置，但不删除之前模式留下的链接；从 contributor 改为 consumer 不会自动卸载贡献 Skill。
172	-
173	-当前支持由 `init.sh` 链接到完整知识仓的安装方式。Skill 脚本依赖同一 checkout 的 `governance/contracts/`，API 流程还依赖相邻 Query Skill；单独复制 Skill 目录并设置知识根不构成完整安装。配置只决定读取哪个知识仓，不补齐脚本依赖，也不复制知识正文。
174		130
175	## 贡献和检查	131	## 贡献和检查
176		132
	@@ -182,7 +138,7 @@ bash init.sh agents /path/to/project contributor
182	bash check.sh	138	bash check.sh
183	```	139	```
184		140
185	-该入口先恢复并校验登记资源，再执行知识 Lint、文档归档受控转换复验、Runbook 正文检查、检索回归、单元测试、Ruff 和 Shell 语法检查。官方 `LICENSE` 原文不参与通用差异空白检查；文档归档 API/Guide 只对保留的来源正文行豁免 Git 空白提示，Frontmatter 与追加的普通链接仍执行通用检查。图谱按需从卡片间现有链接生成，API 引用建议也按需执行，两者都不是入库门禁；CI 保留同一轻量链接构图入口。	141	+该入口恢复并校验登记资源，再执行知识 Lint、归档复验、索引与检索回归、单元测试、Ruff 和 Shell 语法检查。图谱和 API 引用建议按需生成，不属于入库门禁。
186		142
187	## 治理规范	143	## 治理规范
188		144

Mcheck.sh+1-1

	@@ -30,7 +30,7 @@ python3 -m unittest discover -s evals -p 'test_*.py'
30	python3 -m unittest discover -s .agents/skills/ops-knowledge-trace-ingest/scripts -p 'test_*.py'	30	python3 -m unittest discover -s .agents/skills/ops-knowledge-trace-ingest/scripts -p 'test_*.py'
31	python3 .agents/skills/ops-knowledge-trace-ingest/scripts/field_notes_lint.py	31	python3 .agents/skills/ops-knowledge-trace-ingest/scripts/field_notes_lint.py
32	ruff check .agents/skills governance evals	32	ruff check .agents/skills governance evals
33	-bash -n init.sh check.sh get_resources.sh	33	+bash -n install.sh check.sh get_resources.sh
34		34
35	if git rev-parse --is-inside-work-tree >/dev/null 2>&1; then	35	if git rev-parse --is-inside-work-tree >/dev/null 2>&1; then
36	python3 .agents/skills/knowledge-ingest/scripts/fixed_archive_docs.py \	36	python3 .agents/skills/knowledge-ingest/scripts/fixed_archive_docs.py \

Mdocs/design_principles.md+4-4

	@@ -1,6 +1,6 @@
1	# 知识库设计原则	1	# 知识库设计原则
2		2
3	-cannbot-knowledge 不只是一个 Markdown 文件夹。它希望把工程经验整理成可以查询、可以核对来源、也可以长期维护的知识。	3	+cannbot-knowledge 把工程经验整理成可查询、可追溯、可长期维护的 Markdown 知识卡，而不是简单堆放文档。
4		4
5	下面介绍仓库最重要的设计原则。字段和路径的详细规则见[治理规范](../README.md#治理规范)。	5	下面介绍仓库最重要的设计原则。字段和路径的详细规则见[治理规范](../README.md#治理规范)。
6		6
	@@ -16,7 +16,7 @@ cannbot-knowledge 不只是一个 Markdown 文件夹。它希望把工程经验
16	- `docs/` 保存说明文档；	16	- `docs/` 保存说明文档；
17	- `recipes/` 保存场景化操作指南。	17	- `recipes/` 保存场景化操作指南。
18		18
19	-这样可以避免同一条技术知识散落在多个地方。查询工具也只需要从一个位置读取知识。	19	+这样可以避免同一条技术知识散落在多个位置，也让查询工具拥有唯一正文来源。
20		20
21	## 2. 知识既要方便人读，也要方便工具处理	21	## 2. 知识既要方便人读，也要方便工具处理
22		22
	@@ -82,13 +82,13 @@ Query 会先按平台和技术范围过滤，再返回最相关的知识卡。
82	\| `ops-knowledge-vv-ingest` \| 提取不含可达 Cube/AIC 或 MIX_CV 节点的源码级 Operator 卡 \|	82	\| `ops-knowledge-vv-ingest` \| 提取不含可达 Cube/AIC 或 MIX_CV 节点的源码级 Operator 卡 \|
83	\| `ops-knowledge-cv-ingest` \| 提取含可达 Cube/AIC 或 MIX_CV 节点的源码级 Operator 卡 \|	83	\| `ops-knowledge-cv-ingest` \| 提取含可达 Cube/AIC 或 MIX_CV 节点的源码级 Operator 卡 \|
84		84
85	-Query 和 Lint 保持只读。Ingest 可以创建候选卡；trace producer 只在本仓生产 Runbook；VV/CV 只写任务指定的最终 Operator 卡。三类生产能力都不会自动提交或发布。完整边界见 [Knowledge Skills](../governance/specs/skills.md)。	85	+Query 和 Lint 不修改知识正文。Ingest 可以创建候选卡；trace producer 只在本仓生产 Runbook；VV/CV 只写任务指定的最终 Operator 卡。三类生产能力都不会自动提交或发布。完整边界见 [Knowledge Skills](../governance/specs/skills.md)。
86		86
87	## 8. 索引和图谱都可以重新生成	87	## 8. 索引和图谱都可以重新生成
88		88
89	检索索引和本地图谱都是可重建的工具产物，默认不提交。图谱只把知识卡作为节点、卡片之间的普通 Markdown 链接作为有向边，API 与算子关联也来自这些链接；目录索引仍只承担导航。构图按需执行，不回写卡片、不依赖关系缓存，不是知识入库的必做步骤。源码扫描仅在需要 API 引用建议时单独执行，建议不会直接成为图谱边。	89	检索索引和本地图谱都是可重建的工具产物，默认不提交。图谱只把知识卡作为节点、卡片之间的普通 Markdown 链接作为有向边，API 与算子关联也来自这些链接；目录索引仍只承担导航。构图按需执行，不回写卡片、不依赖关系缓存，不是知识入库的必做步骤。源码扫描仅在需要 API 引用建议时单独执行，建议不会直接成为图谱边。
90		90
91	-贡献者仍需维护提交到 Git 的逐层 `index.md` 导航及其摘要；自动重建的是 ignored 的检索索引和图谱。目录导航、检索索引、图谱三者用途不同，不能用其中一个替代另外两个。	91	+贡献者仍需维护提交到 Git 的逐层 `index.md` 导航及其摘要；自动重建的是由 Git 忽略的检索索引和图谱。目录导航、检索索引、图谱三者用途不同，不能用其中一个替代另外两个。
92		92
93	## 需要记住的边界	93	## 需要记住的边界
94		94

Adocs/installation_and_usage.md+214-0

@@ -0,0 +1,214 @@
	1	+# 安装与使用 cannbot-knowledge
	2	+
	3	+`install.sh` 是 cannbot-knowledge 的统一安装入口。本指南说明如何完成安装与验证，以及如何在直接读卡、通用检索和 Ascend C API 专用检索之间选择。
	4	+
	5	+## 安装
	6	+
	7	+### 前置条件
	8	+
	9	+- Bash 和 Python 3.10 或更高版本；安装器默认使用 `python3`，也可通过 `CANNBOT_PYTHON` 指定解释器；
	10	+- 远程取得或更新知识仓需要 Git；在线安装和默认资源恢复还需要 `curl`、`tar`、`mktemp` 与网络；
	11	+- 运行依赖缺失时，所选 Python 需要提供 `pip`，安装器会自动按 `requirements.txt` 安装运行依赖；
	12	+- 已存在的目标项目目录；
	13	+- 目标文件系统支持符号链接。
	14	+
	15	+这里不限定操作系统。Windows 下应在能够提供上述命令和符号链接能力的 Bash 环境中执行。安装器和资源脚本不依赖 GNU `realpath`、`sha256sum` 或 Bash 4 的 `readarray`。
	16	+
	17	+### 在线安装
	18	+
	19	+下面以 Claude Code 和只读消费模式为例：
	20	+
	21	+```bash
	22	+bash -c '
	23	+set -euo pipefail
	24	+installer_file=$(mktemp)
	25	+trap "rm -f \"$installer_file\"" EXIT
	26	+curl -fsSL https://raw.gitcode.com/cann/cannbot-knowledge/raw/master/install.sh \
	27	+ -o "$installer_file"
	28	+bash "$installer_file" "$@"
	29	+' -- claude /path/to/project consumer
	30	+```
	31	+
	32	+命令先把脚本完整下载到临时文件，再交给 Bash 执行；下载失败会直接返回非零状态。若当前网络策略不允许访问 `raw.gitcode.com`，请改用下方的本地安装方式。
	33	+
	34	+把 `claude` 换成当前客户端对应的安装器标识即可。支持 `codex`、`claude`、`opencode`、`trae`、`cursor` 和 `copilot`。第一个参数只选择目录与提示词适配方式，不会执行客户端命令。
	35	+
	36	+远程执行时，安装器默认把官方仓库克隆到 `$HOME/.cannbot/cannbot-knowledge`。该目录已经存在时，只有来源匹配、当前分支正确、已跟踪文件无本地修改且可以快进，安装器才会更新。随后依次完成：
	37	+
	38	+1. 检查当前 Python，并在缺少模块时按 `requirements.txt` 补齐运行依赖；
	39	+2. 运行 `get_resources.sh`，恢复官方文档归档并校验固定提交源码；
	40	+3. 验证或构建只读检索索引；
	41	+4. 在目标项目的 `.agents/skills/` 创建规范 Skill 链接，并为所选客户端创建适配链接；
	42	+5. 把 `CANNBOT_KNOWLEDGE_ROOT` 和安装模式写入项目级 `.cannbot/knowledge.env`；
	43	+6. 向所选客户端的持久指令文件写入带 marker、可重复安装和移除的使用入口。
	44	+
	45	+安装器不会复制 `knowledge/` 正文或修改 shell 启动文件。除使用所选 Python 的 `pip` 补齐运行依赖外，也不修改其他全局配置。Skill 通过符号链接复用同一知识仓 checkout，确保相邻 Skill 与 `governance/contracts/` 版本一致；单独复制 Skill 目录并设置知识根不构成完整安装。资源恢复失败、路径冲突或托管 marker 异常时，安装器会在修改目标项目之前停止。
	46	+
	47	+### 本地安装
	48	+
	49	+无法访问上述 Raw 地址时，先克隆知识仓再执行安装器：
	50	+
	51	+```bash
	52	+git clone https://gitcode.com/cann/cannbot-knowledge.git
	53	+cd cannbot-knowledge
	54	+bash install.sh claude /path/to/project consumer
	55	+```
	56	+
	57	+已经取得仓库时，直接进入知识仓根目录执行最后一条命令。这种方式使用当前 checkout，不自动切换或更新分支。
	58	+
	59	+### 选择安装模式
	60	+
	61	+\| 需求 \| 模式 \| 安装内容 \|
	62	+\|---\|---\|---\|
	63	+\| 查询知识、回答技术问题 \| `consumer` \| `knowledge-query`、`ascendc-api-knowledge-query` \|
	64	+\| 新增或修改知识 \| `contributor` \| 三项基础 Skill、`ascendc-api-knowledge-query`、`ops-knowledge-vv-ingest` 和 `ops-knowledge-cv-ingest` \|
	65	+
	66	+`consumer` 是默认模式。仓内 trace → Runbook 生产使用 `ops-knowledge-trace-ingest`，它不安装到业务项目。安装模式只决定安装器托管的可用 Skill，不改变知识卡内容或可信程度；从 `contributor` 切换为 `consumer` 时，安装器会移除自己创建的贡献类 Skill 链接，并同步已有的托管客户端入口。
	67	+
	68	+### 自定义仓库位置与离线安装
	69	+
	70	+指定托管知识仓位置：
	71	+
	72	+```bash
	73	+bash install.sh codex /path/to/project consumer \
	74	+ --knowledge-root /data/cannbot-knowledge
	75	+```
	76	+
	77	+测试分支或镜像可以显式传入 `--repository-url` 和 `--repository-ref`。更新已有托管知识仓时，当前分支必须与 `--repository-ref` 一致；安装器不会切换其他分支，也不会更新 detached HEAD。
	78	+
	79	+已有知识仓需要完全离线使用时，同时传入 `--knowledge-root`、`--skip-repository-update` 和 `--skip-resources`。这种模式只验证本地 checkout 和仓库结构，不访问或核对远端 origin。跳过资源后，依赖官方文档归档或固定源码的证据核验不可用，因此不应作为普通安装方式。
	80	+
	81	+```bash
	82	+bash install.sh codex /path/to/project consumer \
	83	+ --knowledge-root /data/cannbot-knowledge \
	84	+ --skip-repository-update \
	85	+ --skip-resources
	86	+```
	87	+
	88	+已完成的本地文档缓存默认复用。维护者需要显式获取当前滚动文档归档时，在知识仓中运行：
	89	+
	90	+```bash
	91	+bash get_resources.sh --docs --refresh
	92	+```
	93	+
	94	+刷新只更新 Git 忽略的本地来源，不会自动更新知识卡；后续仍需按 Ingest 流程审查正文、结构和平台差异。
	95	+
	96	+### 验证安装
	97	+
	98	+安装成功后，目标项目应包含 `.cannbot/knowledge.env` 和对应的 Skill 链接。然后在当前 Agent 客户端中发起一次覆盖查询：
	99	+
	100	+> 使用 `knowledge-query` 查看当前知识库实际包含哪些内容。
	101	+
	102	+客户端正常返回真实知识卡统计，即表示托管入口、知识根、索引和运行依赖可用。目录存在或 Skill 链接存在本身不代表索引可用。
	103	+
	104	+通过在线脚本或显式托管目录安装时，重复执行安装命令可以快进更新知识仓并刷新安装；从本地 checkout 执行时，应先自行更新当前分支。只刷新或移除 Agent 托管提示词时使用：
	105	+
	106	+```bash
	107	+bash install.sh codex /path/to/project --prompt-action reinstall
	108	+bash install.sh codex /path/to/project --prompt-action uninstall
	109	+```
	110	+
	111	+`uninstall` 只移除托管提示块，不删除 Skill、知识仓或项目配置；`reinstall` 只重建提示块，不重新安装 Skill。
	112	+
	113	+## 使用
	114	+
	115	+### 先选择入口
	116	+
	117	+\| 问题形态 \| 推荐入口 \|
	118	+\|---\|---\|
	119	+\| 已知准确路径，答案只依赖一张确定的知识卡 \| 直接把知识卡路径提供给 Agent，阅读全文 \|
	120	+\| 不知道卡片路径，或结论需要多张知识卡综合 \| `knowledge-query` \|
	121	+\| Ascend C API 的契约、选型、相关卡片或本地头文件 \| `ascendc-api-knowledge-query`，它复用 `knowledge-query` 的索引和平台规则 \|
	122	+\| 新增、更新或检查知识 \| 使用 `contributor` 模式中的生产与治理 Skill \|
	123	+
	124	+核心判断不是问题长短，而是证据是否已经明确绑定到唯一知识卡。明确单卡时直接读路径最短；需要发现候选、做范围过滤或组合证据时，应进入检索 Skill，不手工遍历知识目录。
	125	+
	126	+### 方式一：直接读取确定的单张知识卡
	127	+
	128	+硬件基础信息、固定概念等内容，如果已经知道唯一知识卡，可以直接给出路径。安装器写入客户端托管入口时，会把知识根解析成实际绝对路径，因此 Agent 不需要继承 shell 环境变量。例如 Ascend 910 95 的平台概念卡对应：
	129	+
	130	+```bash
	131	+cd /path/to/project
	132	+source .cannbot/knowledge.env
	133	+printf '%s\n' "$CANNBOT_KNOWLEDGE_ROOT/knowledge/common/platforms/concepts/ascend_910_95.md"
	134	+```
	135	+
	136	+把命令输出的绝对路径提供给 Agent，例如：
	137	+
	138	+> 请阅读全文 `/absolute/path/to/cannbot-knowledge/knowledge/common/platforms/concepts/ascend_910_95.md`，基于这张卡说明 Ascend 910 95 的基础硬件信息，并注明平台、版本和来源边界。
	139	+
	140	+直接读卡时仍要读取完整 Frontmatter 和正文，核对 `platforms`、生命周期、版本、限制与 `sources`，不能只使用标题或摘要。如果这张卡不足以支持答案，或者问题开始涉及其他 API、算子、调试经验或跨平台比较，应转入相应检索 Skill。
	141	+
	142	+### 方式二：通过通用 Skill 检索和综合
	143	+
	144	+不知道知识路径、需要多个事实共同支撑，或要解决实现、调试、优化、测试、模型、图和 Runtime 问题时，使用 `knowledge-query`。提问时至少说明具体问题、目标技术和目标硬件平台；相关时再补充 CANN 版本。
	145	+
	146	+例如：
	147	+
	148	+> 使用 `knowledge-query` 查询 950 平台上实现 Softmax 时可复用的算子设计、API 约束和已知性能问题。请选择并阅读全文，核对来源后再综合回答。
	149	+
	150	+Skill 返回的路径、标题和摘要只是候选。Agent 必须选择相关卡片、阅读全文并核对平台、版本、限制和来源，之后才能形成结论；不需要打开所有命中或遍历所有链接。
	151	+
	152	+### 方式三：查询 Ascend C API
	153	+
	154	+Ascend C API 查询优先使用 `ascendc-api-knowledge-query`。它负责先确认硬件平台，再复用通用索引召回 API 卡，按需继续读取相关卡片和当前 CANN 包中的头文件。
	155	+
	156	+例如：
	157	+
	158	+> 使用 `ascendc-api-knowledge-query` 查询 950 平台上的 `DataCopyPad`。请阅读全文，说明签名、约束和适用范围；正文不足时再沿相关卡片或我提供的 CANN 包路径核验头文件。
	159	+
	160	+如果需要本机声明或实现证据，还应提供工程实际使用的 CANN 版本和组件包路径。不要把 ACLNN 查询或完整算子实现分析交给这个专用 Skill；这些场景使用 `knowledge-query`。
	161	+
	162	+### 查询前准备的信息
	163	+
	164	+- 要解决的具体问题，例如 API 选型、错误排查或性能优化；
	165	+- 目标技术，例如 Ascend C 或 Triton；
	166	+- 目标硬件平台；
	167	+- 相关时的 CANN 版本和本地包位置；
	168	+- 零命中后是报告知识缺口，还是允许核对其他材料。
	169	+
	170	+平台或技术范围不明确时，应先补充信息，不通过省略过滤条件扩大搜索范围。完整的可追溯回答方法见[形成可追溯回答](../recipes/answer_with_evidence.md)。
	171	+
	172	+### 怎样理解查询结果
	173	+
	174	+\| 看到的信息 \| 它表示什么 \| 它不表示什么 \|
	175	+\|---\|---\|---\|
	176	+\| 覆盖情况 \| 当前有哪些真实知识卡 \| 所有目录和注册分类都有内容 \|
	177	+\| 候选卡 \| 建议继续打开阅读的知识 \| 可以直接使用的最终答案 \|
	178	+\| `status` \| 卡片是草稿、稳定还是废弃 \| 卡片一定正确或经过人工复核 \|
	179	+\| 由 `verified` 派生的信任层级 \| 是否记录了机器或人工复核 \| 卡片适用于所有平台和版本 \|
	180	+\| `sources` \| 可以去哪里核对原始材料 \| 来源一定支持正文全部结论 \|
	181	+\| 零结果 \| 当前条件下没有找到卡片 \| 相关技术不存在 \|
	182	+
	183	+### 没有结果时怎么办
	184	+
	185	+先区分索引错误和有效零命中。索引缺失、损坏或过期时，本次查询无效，应重新运行安装器或由知识仓维护者准备索引。
	186	+
	187	+索引正常时，再检查目标范围是否确有知识、平台/状态/技术条件是否正确、正文版本边界是否适用，以及 API 名、错误码或关键词是否准确。不要用其他平台或 DSL 的卡片填补结果。仍无结果时，应说明查询范围、已检查条件和下一步建议，不能据此判断相关技术不存在。
	188	+
	189	+## 贡献知识
	190	+
	191	+贡献知识使用 `contributor` 模式。开始前先用 `knowledge-query` 搜索同一主题并阅读已有卡片，明确采用 create、update、merge、split、deprecate 或 defer；随后使用匹配的生产 Skill，更新导航和日志，并通过 `knowledge-lint` 与目标查询验证。
	192	+
	193	+完整流程见[贡献知识](../recipes/contribute_knowledge.md)，正式要求以 [CONTRIBUTING.md](../CONTRIBUTING.md) 为准。仓内 `ops-knowledge-trace-ingest` 仅用于从开发轨迹生产 Runbook，不是业务项目安装项。
	194	+
	195	+## 常见问题
	196	+
	197	+\| 问题 \| 处理方式 \|
	198	+\|---\|---\|
	199	+\| 仓库无法克隆或更新 \| 检查网络、仓库地址与分支；现有托管 checkout 有本地改动或无法快进时先人工处理，不由安装器覆盖 \|
	200	+\| `No module named yaml` \| 重新执行安装命令让安装器补齐依赖；若自动安装失败，检查当前 Python 的 `pip` 是否可用及其错误输出 \|
	201	+\| 资源恢复失败 \| 保留错误输出；检查网络或已存在但不完整的对应资源目录，不要让安装器覆盖它 \|
	202	+\| Skill 路径冲突 \| 检查目标项目中的同名路径；安装器不会覆盖非本次安装创建的文件或目录 \|
	203	+\| 索引不可用 \| 重新执行安装命令；仍失败时由知识仓维护者重建或检查索引 \|
	204	+\| 平台或技术不明确 \| 补充真实目标范围，不扩大查询 \|
	205	+\| 多张卡片结论冲突 \| 比较平台、版本、生命周期和来源；证据仍不足时保留冲突 \|
	206	+
	207	+## 继续阅读
	208	+
	209	+- [设计原则](design_principles.md)
	210	+- [形成可追溯回答](../recipes/answer_with_evidence.md)
	211	+- [使用知识库进行算子开发](../recipes/operator_development.md)
	212	+- [贡献知识](../recipes/contribute_knowledge.md)
	213	+- [使用知识库查询 API](../recipes/api_search.md)
	214	+- [Knowledge Skills](../governance/specs/skills.md)

Ddocs/user_guide.md+0-101

	@@ -1,101 +0,0 @@
1	-# 知识库用户指南
2	-
3	-这份指南介绍怎样使用 cannbot-knowledge 查询和贡献知识。安装方法见根 [README](../README.md#安装到项目)。
4	-
5	-## 选择使用模式
6	-
7	-\| 你要做什么 \| 使用模式 \| 可用 Skill \|
8	-\|---\|---\|---\|
9	-\| 查询知识、回答技术问题 \| `consumer` \| `knowledge-query`、`ascendc-api-knowledge-query` \|
10	-\| 新增或修改知识 \| `contributor` \| 三项基础 Skill、`ascendc-api-knowledge-query`，以及源码级算子使用的 `ops-knowledge-vv-ingest`、`ops-knowledge-cv-ingest`；仓内 trace 生产另用不安装到业务项目的 `ops-knowledge-trace-ingest` \|
11	-
12	-使用模式只决定安装哪些 Skill，不会改变知识卡的内容或可信程度。
13	-
14	-## 查询前准备哪些信息
15	-
16	-最好先明确下面几项：
17	-
18	-- 要解决什么问题，例如查询 API、排查错误或优化性能；
19	-- 使用哪种技术，例如 Ascend C 或 Triton；
20	-- 目标平台是什么；
21	-- 问题是否和 CANN 版本有关；
22	-- 没有结果时，是报告知识缺口还是继续查找其他材料。
23	-
24	-例如可以这样告诉 Agent：
25	-
26	-> 使用 `knowledge-query` 查找 A2 平台上 Ascend C 的目标 API 约束。请打开知识卡并核对来源。如果没有结果，请说明当前知识缺口，不要使用其他 DSL 的结论代替。
27	-
28	-如果平台或技术范围无法确认，应先补充信息。不要通过省略条件来扩大搜索范围。
29	-
30	-## 怎样完成一次查询
31	-
32	-1. 明确问题。一次先解决一个具体问题。复杂问题可以拆成多个小问题分别查询。
33	-2. 查看覆盖情况。确认目标范围内是否真的有知识卡。只有目录不代表已经有知识。
34	-3. 按真实条件搜索。保留需要的平台和技术条件。记录 CANN 版本供命中后核对正文，但当前不把它作为搜索过滤条件。
35	-4. 打开知识卡。搜索摘要只用来选择卡片，不能直接当作答案。
36	-5. 核对内容。阅读结论、适用条件、限制和完整来源。
37	-6. 整理回答。说明结论适用于什么范围、依据是什么、还有哪些内容需要验证。
38	-
39	-完整检查步骤见[形成可追溯回答](../recipes/answer_with_evidence.md)。具体查询方式见 [`knowledge-query`](../.agents/skills/knowledge-query/SKILL.md)。
40	-
41	-Ascend C API 问题可直接使用 [`ascendc-api-knowledge-query`](../.agents/skills/ascendc-api-knowledge-query/SKILL.md)。它先识别目标硬件并按平台检索，阅读全文后根据当前问题选择相关卡片或头文件，不遍历全部链接。需要本机声明/实现时，提供工程使用的 CANN 版本和包路径；相对头文件线索必须结合正确的 AscendC 包布局解析，不能按知识仓目录打开。
42	-
43	-## 怎样理解查询结果
44	-
45	-\| 看到的信息 \| 它表示什么 \| 它不表示什么 \|
46	-\|---\|---\|---\|
47	-\| 覆盖情况 \| 当前有哪些真实知识卡 \| 所有目录和已注册分类都有内容 \|
48	-\| 候选卡 \| 建议继续打开阅读的知识 \| 可以直接使用的最终答案 \|
49	-\| `status` \| 卡片是草稿、稳定还是废弃 \| 卡片一定正确或经过人工复核 \|
50	-\| 信任层级 \| 是否记录了机器或人工复核 \| 卡片适用于所有平台和版本 \|
51	-\| `sources` \| 可以去哪里核对原始材料 \| 来源一定能支持正文中的全部结论 \|
52	-\| 零结果 \| 当前条件下没有找到卡片 \| 相关技术不存在 \|
53	-
54	-## 没有结果时怎么办
55	-
56	-先检查索引是否正常。如果索引缺失、损坏或过期，本次查询无效，应先修复索引。
57	-
58	-索引正常时，再检查：
59	-
60	-1. 目标范围内是否真的有知识卡；
61	-2. 平台、状态和技术条件是否正确，以及命中正文的版本边界是否适用；
62	-3. API 名、错误码或关键词是否写对；
63	-4. 是否确实存在尚未收录的知识。
64	-
65	-精确 API 名在目标平台的 stable 查询零命中时，按对应查询 Skill 独立补搜平台未定位的 draft 卡。这些结果只提供待核验线索，不并入原平台结果；具体补搜入口见[API 查询实践](../recipes/api_search.md)。
66	-
67	-不要用其他平台或其他 DSL 的卡片填补结果。如果补搜仍然没有结果，应说明查询范围、已经检查的条件和下一步建议，不能直接判断相关技术不存在。
68	-
69	-## 怎样贡献知识
70	-
71	-贡献知识前，先搜索同一主题并阅读已有卡片。然后选择一种处理方式：
72	-
73	-- `create`：新增知识；
74	-- `update`：更新已有卡片；
75	-- `merge`：合并重复卡片；
76	-- `split`：拆分职责过多的卡片；
77	-- `deprecate`：废弃错误或过时结论；
78	-- `defer`：信息不足，暂不落库。
79	-
80	-确定处理方式后，再选择路径、准备来源和编写知识卡。最后更新导航与日志、运行全库 Lint，由知识仓维护者准备与改动后内容一致的检索索引，再确认新知识可以被目标查询找到。Query 本身不会重建索引；索引准备方式见其规范 Skill。
81	-
82	-完整流程见[贡献知识](../recipes/contribute_knowledge.md)，正式要求以 [CONTRIBUTING.md](../CONTRIBUTING.md) 为准。
83	-
84	-## 常见问题
85	-
86	-\| 问题 \| 处理方式 \|
87	-\|---\|---\|
88	-\| 索引不可用 \| 停止查询，由安装器或仓库维护者重新准备索引 \|
89	-\| 平台或技术不明确 \| 请求补充信息，不扩大范围 \|
90	-\| Lint 报错 \| 根据错误找到对应规则或知识卡并修复 \|
91	-\| 来源不足 \| 缩小结论、保留为 draft，或选择 defer \|
92	-\| 多张卡片结论冲突 \| 比较平台、版本、来源和更新时间，暂时保留冲突 \|
93	-
94	-## 继续阅读
95	-
96	-- [设计原则](design_principles.md)
97	-- [形成可追溯回答](../recipes/answer_with_evidence.md)
98	-- [使用知识库进行算子开发](../recipes/operator_development.md)
99	-- [贡献知识](../recipes/contribute_knowledge.md)
100	-- [使用知识库查询 API](../recipes/api_search.md)
101	-- [治理规范](../README.md#治理规范)

Mevals/test_documentation.py+47-4

	@@ -11,14 +11,14 @@
11	from __future__ import annotations	11	from __future__ import annotations
12		12
13	import ast	13	import ast
		14	+import importlib.util
14	import json	15	import json
15	import os	16	import os
16	-import tarfile
17	-import importlib.util
18	import re	17	import re
19	import shutil	18	import shutil
20	import subprocess	19	import subprocess
21	import sys	20	import sys
		21	+import tarfile
22	import tempfile	22	import tempfile
23	import unittest	23	import unittest
24	from argparse import ArgumentParser, _SubParsersAction	24	from argparse import ArgumentParser, _SubParsersAction
	@@ -55,6 +55,7 @@ class DocumentationContractTests(unittest.TestCase):
55	self.root / "CONTRIBUTING.md",	55	self.root / "CONTRIBUTING.md",
56	self.root / "AGENTS.md",	56	self.root / "AGENTS.md",
57	self.root / "CLAUDE.md",	57	self.root / "CLAUDE.md",
		58	+ self.root / "docs",
58	self.root / "governance/specs",	59	self.root / "governance/specs",
59	self.root / ".agents/skills",	60	self.root / ".agents/skills",
60	self.root / "docs",	61	self.root / "docs",
	@@ -76,6 +77,7 @@ class DocumentationContractTests(unittest.TestCase):
76	self.root / "CONTRIBUTING.md",	77	self.root / "CONTRIBUTING.md",
77	self.root / "AGENTS.md",	78	self.root / "AGENTS.md",
78	self.root / "CLAUDE.md",	79	self.root / "CLAUDE.md",
		80	+ self.root / "docs",
79	self.root / "governance/specs",	81	self.root / "governance/specs",
80	]	82	]
81	roots.extend((self.root / "docs", self.root / "recipes"))	83	roots.extend((self.root / "docs", self.root / "recipes"))
	@@ -242,6 +244,32 @@ class DocumentationContractTests(unittest.TestCase):
242	failures = [path.relative_to(self.root).as_posix() for path in documents if "安装 Profile" in path.read_text(encoding="utf-8")]	244	failures = [path.relative_to(self.root).as_posix() for path in documents if "安装 Profile" in path.read_text(encoding="utf-8")]
243	self.assertEqual([], failures)	245	self.assertEqual([], failures)
244		246
		247	+ def test_installation_and_usage_have_one_documented_entry(self) -> None:
		248	+ readme = (self.root / "README.md").read_text(encoding="utf-8")
		249	+ guide = (self.root / "docs/installation_and_usage.md").read_text(encoding="utf-8")
		250	+ self.assertIn("docs/installation_and_usage.md", readme)
		251	+ self.assertNotIn("## 环境准备", readme)
		252	+ self.assertNotIn("## 安装到项目", readme)
		253	+ self.assertNotIn("## 使用知识库", readme)
		254	+ for required in (
		255	+ "install.sh",
		256	+ "get_resources.sh",
		257	+ ".cannbot/knowledge.env",
		258	+ "knowledge-query",
		259	+ "ascendc-api-knowledge-query",
		260	+ "knowledge/common/platforms/concepts/ascend_910_95.md",
		261	+ ):
		262	+ self.assertIn(required, guide)
		263	+ for client in ("codex", "claude", "opencode", "trae", "cursor", "copilot"):
		264	+ self.assertIn(f"`{client}`", guide)
		265	+ self.assertNotIn("支持 `agents`", guide)
		266	+ self.assertNotIn("Linux 或 macOS", guide)
		267	+ self.assertNotIn("\| bash", guide)
		268	+ self.assertIn('-o "$installer_file"', guide)
		269	+ self.assertIn("自动按 `requirements.txt` 安装运行依赖", guide)
		270	+ self.assertTrue((self.root / "install.sh").is_file())
		271	+ self.assertFalse((self.root / "init.sh").exists())
		272	+
245	def test_knowledge_cards_use_okf_core_fields(self) -> None:	273	def test_knowledge_cards_use_okf_core_fields(self) -> None:
246	root_index = (self.root / "knowledge/index.md").read_text(encoding="utf-8")	274	root_index = (self.root / "knowledge/index.md").read_text(encoding="utf-8")
247	root_metadata = yaml.safe_load(root_index.split("---", 2)[1])	275	root_metadata = yaml.safe_load(root_index.split("---", 2)[1])
	@@ -514,7 +542,7 @@ class DocumentationContractTests(unittest.TestCase):
514	"AGENTS.md",	542	"AGENTS.md",
515	"CONTRIBUTING.md",	543	"CONTRIBUTING.md",
516	"docs/design_principles.md",	544	"docs/design_principles.md",
517	- "docs/user_guide.md",	545	+ "docs/installation_and_usage.md",
518	"governance/specs/skills.md",	546	"governance/specs/skills.md",
519	):	547	):
520	text = (self.root / relative).read_text(encoding="utf-8")	548	text = (self.root / relative).read_text(encoding="utf-8")
	@@ -650,6 +678,21 @@ class DocumentationContractTests(unittest.TestCase):
650	failures.append(f"{document.relative_to(self.root)}: {token}")	678	failures.append(f"{document.relative_to(self.root)}: {token}")
651	self.assertEqual([], failures)	679	self.assertEqual([], failures)
652		680
		681	+ def test_document_archive_fetch_is_portable_and_is_ignored(self) -> None:
		682	+ script = (self.root / "get_resources.sh").read_text(encoding="utf-8")
		683	+ ignored = (self.root / ".gitignore").read_text(encoding="utf-8").splitlines()
		684	+ self.assertIn("cann-docs-raw/", ignored)
		685	+ self.assertIn('${BASH_SOURCE[0]}', script)
		686	+ self.assertIn("mktemp -d", script)
		687	+ self.assertIn("archive_url", script)
		688	+ self.assertIn("--refresh", script)
		689	+ self.assertIn('PYTHON_BIN="${CANNBOT_PYTHON:-python3}"', script)
		690	+ for non_portable_command in ("readarray", "sha256sum", "realpath"):
		691	+ self.assertNotIn(non_portable_command, script)
		692	+ self.assertIn("repair_published_code_links", script)
		693	+ self.assertIn("repair_fixed_archive.py", script)
		694	+ self.assertIn("Refusing to overwrite incomplete source directory", script)
		695	+
653	def test_document_archive_download_refresh_and_failure_preserve_cache(self) -> None:	696	def test_document_archive_download_refresh_and_failure_preserve_cache(self) -> None:
654	with tempfile.TemporaryDirectory() as temporary:	697	with tempfile.TemporaryDirectory() as temporary:
655	root = Path(temporary)	698	root = Path(temporary)
	@@ -737,7 +780,7 @@ class DocumentationContractTests(unittest.TestCase):
737	module.repair_tree(root, write=True)	780	module.repair_tree(root, write=True)
738	self.assertEqual(before, source.read_bytes())	781	self.assertEqual(before, source.read_bytes())
739		782
740	- def test_ingest_distinguishes_git_and_fixed_archive_reference(self) -> None:	783	+ def test_ingest_distinguishes_git_and_document_archive_reference(self) -> None:
741	skill = (	784	skill = (
742	self.root / ".agents/skills/knowledge-ingest/SKILL.md"	785	self.root / ".agents/skills/knowledge-ingest/SKILL.md"
743	).read_text(encoding="utf-8")	786	).read_text(encoding="utf-8")

Mevals/test_installer.py+471-38

	@@ -11,6 +11,7 @@
11	from __future__ import annotations	11	from __future__ import annotations
12		12
13	import json	13	import json
		14	+import os
14	import re	15	import re
15	import shutil	16	import shutil
16	import subprocess	17	import subprocess

Mget_resources.sh+37-6

	@@ -13,9 +13,14 @@
13	set -euo pipefail	13	set -euo pipefail
14		14
15	SCRIPT_DIR=$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)	15	SCRIPT_DIR=$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)
		16	+PYTHON_BIN="${CANNBOT_PYTHON:-python3}"
16	RESOURCE_SCOPE="--all"	17	RESOURCE_SCOPE="--all"
17	REFRESH_DOCS=false	18	REFRESH_DOCS=false
18	-usage() { echo "usage: get_resources.sh [--all\|--docs\|--code] [--refresh]"; }	19	+
		20	+usage() {
		21	+ echo "usage: get_resources.sh [--all\|--docs\|--code] [--refresh]"
		22	+}
		23	+
19	for option in "$@"; do	24	for option in "$@"; do
20	case "$option" in	25	case "$option" in
21	--all\|--docs\|--code) RESOURCE_SCOPE="$option" ;;	26	--all\|--docs\|--code) RESOURCE_SCOPE="$option" ;;
	@@ -28,16 +33,35 @@ if [[ "$RESOURCE_SCOPE" == "--code" && "$REFRESH_DOCS" == "true" ]]; then
28	echo "--refresh applies only to documentation" >&2	33	echo "--refresh applies only to documentation" >&2
29	exit 2	34	exit 2
30	fi	35	fi
		36	+command -v "$PYTHON_BIN" >/dev/null 2>&1 \|\| {
		37	+ echo "Missing Python interpreter: $PYTHON_BIN" >&2
		38	+ exit 1
		39	+}
31		40
32	fetch_documents() (	41	fetch_documents() (
		42	+for required_command in curl tar mktemp; do
		43	+ command -v "$required_command" >/dev/null 2>&1 \|\| {
		44	+ echo "Missing required command: $required_command" >&2
		45	+ exit 1
		46	+ }
		47	+done
		48	+
33	TARGET_DIR="$SCRIPT_DIR/cann-docs-raw"	49	TARGET_DIR="$SCRIPT_DIR/cann-docs-raw"
34	REGISTRIES="$SCRIPT_DIR/governance/schemas/registries.yaml"	50	REGISTRIES="$SCRIPT_DIR/governance/schemas/registries.yaml"
35	REPAIR_SCRIPT="$SCRIPT_DIR/.agents/skills/knowledge-ingest/scripts/repair_fixed_archive.py"	51	REPAIR_SCRIPT="$SCRIPT_DIR/.agents/skills/knowledge-ingest/scripts/repair_fixed_archive.py"
36	-URL=$(python3 - "$REGISTRIES" <<'PYTHON'	52	+
		53	+if [[ ! -f "$REGISTRIES" ]]; then
		54	+ echo "Missing governance registry: $REGISTRIES" >&2
		55	+ exit 1
		56	+fi
		57	+
		58	+URL=$("$PYTHON_BIN" - "$REGISTRIES" <<'PYTHON'
37	import re	59	import re
38	import sys	60	import sys
39	from pathlib import Path	61	from pathlib import Path
		62	+
40	import yaml	63	import yaml
		64	+
41	source = yaml.safe_load(Path(sys.argv[1]).read_text(encoding="utf-8"))["local_sources"]["cann_docs_raw"]	65	source = yaml.safe_load(Path(sys.argv[1]).read_text(encoding="utf-8"))["local_sources"]["cann_docs_raw"]
42	url = source.get("archive_url")	66	url = source.get("archive_url")
43	if not isinstance(url, str) or not re.fullmatch(r"https://[^\s/?#@]+/[^\s#]+", url):	67	if not isinstance(url, str) or not re.fullmatch(r"https://[^\s/?#@]+/[^\s#]+", url):
	@@ -49,14 +73,21 @@ PYTHON
49	repair_published_code_links() {	73	repair_published_code_links() {
50	local source_root="$1/asc-devkit/docs/zh"	74	local source_root="$1/asc-devkit/docs/zh"
51	[[ -d "$source_root" ]] \|\| return 0	75	[[ -d "$source_root" ]] \|\| return 0
52	- python3 "$REPAIR_SCRIPT" sync --source-root "$source_root"	76	+ if [[ ! -f "$REPAIR_SCRIPT" ]]; then
		77	+ echo "Missing fixed archive repair script: $REPAIR_SCRIPT" >&2
		78	+ exit 1
		79	+ fi
		80	+ "$PYTHON_BIN" "$REPAIR_SCRIPT" sync --source-root "$source_root"
53	}	81	}
		82	+
54	write_complete_marker() {	83	write_complete_marker() {
55	- printf 'archive_url=%s\nprepared_at=%s\n' "$URL" "$(date -u '+%Y-%m-%dT%H:%M:%SZ')" > "$1/.complete"	84	+ printf 'archive_url=%s\nprepared_at=%s\n' \
		85	+ "$URL" "$(date -u '+%Y-%m-%dT%H:%M:%SZ')" > "$1/.complete"
56	}	86	}
57		87
58	if [[ -e "$TARGET_DIR" \|\| -L "$TARGET_DIR" ]]; then	88	if [[ -e "$TARGET_DIR" \|\| -L "$TARGET_DIR" ]]; then
59	- if [[ -L "$TARGET_DIR" \|\| ! -d "$TARGET_DIR" \|\| -L "$TARGET_DIR/.complete" \|\| ! -f "$TARGET_DIR/.complete" ]]; then	89	+ if [[ -L "$TARGET_DIR" \|\| ! -d "$TARGET_DIR" \|\| \
		90	+ -L "$TARGET_DIR/.complete" \|\| ! -f "$TARGET_DIR/.complete" ]]; then
60	echo "Refusing to overwrite incomplete source directory: $TARGET_DIR" >&2	91	echo "Refusing to overwrite incomplete source directory: $TARGET_DIR" >&2
61	exit 1	92	exit 1
62	fi	93	fi
	@@ -102,6 +133,6 @@ if [[ "$RESOURCE_SCOPE" != "--code" ]]; then
102	fetch_documents	133	fetch_documents
103	fi	134	fi
104	if [[ "$RESOURCE_SCOPE" != "--docs" ]]; then	135	if [[ "$RESOURCE_SCOPE" != "--docs" ]]; then
105	- python3 "$SCRIPT_DIR/.agents/skills/knowledge-ingest/scripts/source_resources.py" \	136	+ "$PYTHON_BIN" "$SCRIPT_DIR/.agents/skills/knowledge-ingest/scripts/source_resources.py" \
106	--knowledge-root "$SCRIPT_DIR" fetch	137	--knowledge-root "$SCRIPT_DIR" fetch
107	fi	138	fi

Mgovernance/specs/frontmatter.md+4-3

Mgovernance/specs/okf.md+4-2

	@@ -32,7 +32,9 @@ OKF 规定通用交换格式；CANNBot Profile 规定本仓允许哪些路径、
32		32
33	例如 `knowledge/ops/ascendc/apis/datacopypad_gm_to_ub.md` 的 Concept ID 是 `ops/ascendc/apis/datacopypad_gm_to_ub`。	33	例如 `knowledge/ops/ascendc/apis/datacopypad_gm_to_ub.md` 的 Concept ID 是 `ops/ascendc/apis/datacopypad_gm_to_ub`。
34		34
35	-Concept 间的本地 Markdown 链接必须解析到同一 `knowledge/` Bundle；索引也只能导航 Bundle 内文件。知识卡可额外链接 Registry 登记的固定提交本地源码文件（可带 `#L行号`），这类链接只是来源导航，不是 Concept Link，不生成源码节点或图谱边。其他 Bundle 外材料使用 HTTP(S) 来源，不用仓库相对路径把 Concept 绑定到治理设施。行内代码和代码围栏中的 Markdown-like 片段不构成 Link；列表容器缩进后的围栏同样按代码处理。	35	+Concept 间的本地 Markdown 链接必须解析到同一 `knowledge/` Bundle；索引也只能导航 Bundle 内文件。知识卡可额外链接 Registry 登记的固定提交本地源码文件（可带 `#L行号`），这类链接只是来源导航，不是 Concept Link，也不生成源码节点或图谱边。
		36	+
		37	+其他 Bundle 外材料使用 HTTP(S) 来源，不用仓库相对路径把 Concept 绑定到治理设施。行内代码和代码围栏中的 Markdown-like 片段不构成 Link；列表容器缩进后的围栏同样按代码处理。
36		38
37	正文图片不形成 Concept Link 或图谱边，必须使用带 40 位 commit 和具体文件路径的 HTTPS Git raw URL；Lint 仅离线校验 URL 形状。	39	正文图片不形成 Concept Link 或图谱边，必须使用带 40 位 commit 和具体文件路径的 HTTPS Git raw URL；Lint 仅离线校验 URL 形状。
38		40
	@@ -64,7 +66,7 @@ OKF 通用 consumer 应容忍未知 `type`、扩展字段、断链和缺失索
64	- Ingest 只生成 CANNBot Profile 接受的候选 Concept；	66	- Ingest 只生成 CANNBot Profile 接受的候选 Concept；
65	- Query 在加载时拒绝不符合 CANNBot Profile 的卡片，不承诺读取任意第三方 OKF Bundle；	67	- Query 在加载时拒绝不符合 CANNBot Profile 的卡片，不承诺读取任意第三方 OKF Bundle；
66	- Lint 检查字段白名单、受控路径、索引完整性和链接可达性，严格程度高于 OKF 最小要求；	68	- Lint 检查字段白名单、受控路径、索引完整性和链接可达性，严格程度高于 OKF 最小要求；
67	-- 本地图谱按需从 Concept 之间的普通 Markdown 链接生成，仅包含 Concept 节点和有向 `links_to` 边，包括 API 与算子卡片之间的链接；Index 只用于导航。构图不依赖关系判定缓存，不维护专用关系块，不回写 Concept，也不是入库门禁。图谱和可视化全部位于 ignored 的 `artifacts/graphs/`，不提交。	69	+- 本地图谱按需从 Concept 之间的普通 Markdown 链接生成，仅包含 Concept 节点和有向 `links_to` 边，包括 API 与算子卡片之间的链接；Index 只用于导航。构图不依赖关系判定缓存，不维护专用关系块，不回写 Concept，也不是入库门禁。图谱和可视化全部位于 Git 忽略的 `artifacts/graphs/`，不提交。
68		70
69	这些限制是作者质量门禁，不应被描述成 OKF 对所有 consumer 的要求。	71	这些限制是作者质量门禁，不应被描述成 OKF 对所有 consumer 的要求。
70		72

Mgovernance/specs/paths.md+3-1

	@@ -33,7 +33,9 @@ route 是 technology 或 scope 的统称。当前允许的组合如下：
33		33
34	route 后必须出现路径 Profile，例如 `knowledge/common/platforms/concepts/`。`interoperability` 只能放在同一 domain 的 `shared/` 下。	34	route 后必须出现路径 Profile，例如 `knowledge/common/platforms/concepts/`。`interoperability` 只能放在同一 domain 的 `shared/` 下。
35		35
36	-Registry 允许某种组合，只表示工具能够识别它，不表示仓库已有相应知识。Contract 要求 Registry 中注册的所有 domain 根目录始终存在；domain Registry 中设置 `precreate_routes: true` 的 `ops` 和 `model` 还预建各自注册 route。`common`、`contrib`、`graph`、`runtime` 不预建没有真实知识的下一层路径，由领域维护者随首张卡物化。所有 index-only 入口都不计入 Query 覆盖，route 下的具体 Profile 也不全量预建。	36	+Registry 允许某种组合，只表示工具能够识别它，不表示仓库已有相应知识。Contract 要求 Registry 中注册的所有 domain 根目录始终存在；设置 `precreate_routes: true` 的 `ops` 和 `model` 还预建各自注册 route。
		37	+
		38	+`common`、`contrib`、`graph`、`runtime` 不预建没有真实知识的下一层路径，由领域维护者随首张卡物化。所有 index-only 入口都不计入 Query 覆盖，route 下的具体 Profile 也不全量预建。
37		39
38	当前路径 Profile 是全局集合：经过 route 的路径默认可以选择任一已注册 Profile，但内容必须符合该 Profile 的职责。机器规则另行限制 `interoperability` 只能位于 `shared`，并限制 Operator 与 Runbook 的附加层级。若以后需要禁止某个 domain-route 与 Profile 的组合，应在 Registry、Contract 和接受/拒绝测试中明确增加规则，不能只写在文档里。	40	当前路径 Profile 是全局集合：经过 route 的路径默认可以选择任一已注册 Profile，但内容必须符合该 Profile 的职责。机器规则另行限制 `interoperability` 只能位于 `shared`，并限制 Operator 与 Runbook 的附加层级。若以后需要禁止某个 domain-route 与 Profile 的组合，应在 Registry、Contract 和接受/拒绝测试中明确增加规则，不能只写在文档里。
39		41

Mgovernance/specs/schemas.md+10-4

	@@ -15,7 +15,9 @@
15		15
16	同一规则只能有一个机器事实源：字段形状归 JSON Schema，字段组合和 `okf_type` 归 Profile，受控值归 Registry，依赖路径、其他字段或其他文件的关系归 Contract。	16	同一规则只能有一个机器事实源：字段形状归 JSON Schema，字段组合和 `okf_type` 归 Profile，受控值归 Registry，依赖路径、其他字段或其他文件的关系归 Contract。
17		17
18	-顶层字段是否必选只由 `profiles.yaml` 的 `common_required` 与各 Profile `required` 声明；Frontmatter Schema 不重复顶层 `required`，但仍负责 `sources[].resource`、`verified.by/at` 等嵌套对象的必选字段。`title` 和 `description` 的字符串类型归 Schema，非空文本语义归 Profile 检查。Contract 直接消费这些声明，只保留现有的可加载性和 `okf_type` 基础检查，不增加 required/optional 重复、交叉或 Schema 字段名单等 Profile 声明自校验层。	18	+顶层字段是否必选只由 `profiles.yaml` 的 `common_required` 与各 Profile `required` 声明。Frontmatter Schema 不重复顶层 `required`，但仍负责 `sources[].resource`、`verified.by/at` 等嵌套对象的必选字段。`title` 和 `description` 的字符串类型归 Schema，非空文本语义归 Profile 检查。
		19	+
		20	+Contract 直接消费这些声明，只保留现有的可加载性和 `okf_type` 基础检查，不增加 required/optional 重复、交叉或 Schema 字段名单等 Profile 声明自校验层。
19		21
20	## Registry 分区	22	## Registry 分区
21		23
	@@ -30,9 +32,13 @@
30	\| `platforms` \| 卡片适用平台 ID \| Frontmatter 校验和 platform 过滤 \|	32	\| `platforms` \| 卡片适用平台 ID \| Frontmatter 校验和 platform 过滤 \|
31	\| `tags` \| task、topic、paradigm 三个维度的规范标签 \| 标签校验、任务映射、过滤和召回 \|	33	\| `tags` \| task、topic、paradigm 三个维度的规范标签 \| 标签校验、任务映射、过滤和召回 \|
32		34
33	-`local_sources` 以 `kind: git` 声明固定源码资源，包含安全的仓库相对 `root`、可执行 `fetch_script`、规范 `repository` 和非空、去重、排序的 40 位 `revisions`；Git 根可多级组织，根之间必须唯一且无祖先/后代重叠，规范仓库身份也不能重复，不得使用知识或治理设施目录。无 `kind` 或 `kind: archive` 保持归档顶层根语义，要求 HTTPS `archive_url`，不登记或校验归档/内容树 SHA-256；Git 定义不能混入归档字段。Contract 共用完整来源根匹配、来源解析和 checkout 校验；源码不属于 Bundle，不形成图谱节点。离线缺根允许校验路径形状，根已存在时必须检查版本与文件。	35	+`local_sources` 以 `kind: git` 声明固定源码资源，包含安全的仓库相对 `root`、可执行 `fetch_script`、规范 `repository` 和非空、去重、排序的 40 位 `revisions`。Git 根可多级组织，根之间必须唯一且无祖先/后代重叠；规范仓库身份也不能重复，且不得使用知识或治理设施目录。
34		36
35	-文档归档 `mirror` 的转换策略同样由 Registry 声明。当前 `navigation_policy: index_only` 表示 README、发布占位、纯链接目录和接口清单不形成 Concept，来源链接改到最近的有效目录 `index.md`；`omit_section_title_contains` 声明只进入结构化元数据、不在知识正文重复保留的章节标题片段。`api_operator_display_limit` 是正整数，只限制按需 API 引用建议的展示数量，完整调用证据保存在 ignored 审计报告中，不限制现有正文链接或图谱边。同步器和 Lint 必须共同消费这些声明，不能各自维护隐藏例外。	37	+无 `kind` 或使用 `kind: archive` 时保持归档顶层根语义，要求 HTTPS `archive_url`，不登记或校验归档与内容树 SHA-256；Git 定义不能混入归档字段。Contract 共用完整来源根匹配、来源解析和 checkout 校验。源码不属于 Bundle，不形成图谱节点；离线缺根时只校验路径形状，根已存在时再检查版本与文件。
		38	+
		39	+文档归档 `mirror` 的转换策略同样由 Registry 声明。当前 `navigation_policy: index_only` 表示 README、发布占位、纯链接目录和接口清单不形成 Concept，来源链接改到最近的有效目录 `index.md`；`omit_section_title_contains` 声明只进入结构化元数据、不在知识正文重复保留的章节标题片段。
		40	+
		41	+`api_operator_display_limit` 是正整数，只限制按需 API 引用建议的展示数量。完整调用证据保存在由 Git 忽略的审计报告中，不限制现有正文链接或图谱边。同步器和 Lint 必须共同消费这些声明，不能各自维护隐藏例外。
36		42
37	Contract 对 API/Guide 的归档镜像识别只采用 `primary` 来源；未声明 `role` 的旧来源保留原有匹配行为。显式标为 `supporting`、`example` 等非主来源的归档引用不把整张蒸馏卡变成镜像：卡片仍遵守普通正文约束，也不从辅助文档推导整卡平台。镜像可以保留原文多个 H1，但无 H1 仍失败。正文、平台和文档回归共同调用这一判定；实际镜像的来源绑定、正文保真和元数据仍由文档归档复验检查，不通过改写来源角色跳过复验。	43	Contract 对 API/Guide 的归档镜像识别只采用 `primary` 来源；未声明 `role` 的旧来源保留原有匹配行为。显式标为 `supporting`、`example` 等非主来源的归档引用不把整张蒸馏卡变成镜像：卡片仍遵守普通正文约束，也不从辅助文档推导整卡平台。镜像可以保留原文多个 H1，但无 H1 仍失败。正文、平台和文档回归共同调用这一判定；实际镜像的来源绑定、正文保真和元数据仍由文档归档复验检查，不通过改写来源角色跳过复验。
38		44
	@@ -60,7 +66,7 @@ technology 与 scope 的 ID 不得重叠；每个 route 必须声明允许出现
60	本地图谱构建前校验	66	本地图谱构建前校验
61	```	67	```
62		68
63	-图谱复用同一 Contract 校验知识卡和正文链接，仅以 Concept 为节点、卡片间已有 Markdown 链接为有向 `links_to` 边；API 与算子关联也使用这些链接。Index 不进入图谱，不从目录或语义相似性推断边。构图按需执行，只在 ignored 的 `artifacts/graphs/` 写派生产物，不依赖判定缓存或回写知识卡。	69	+图谱复用同一 Contract 校验知识卡和正文链接，仅以 Concept 为节点、卡片间已有 Markdown 链接为有向 `links_to` 边；API 与算子关联也使用这些链接。Index 不进入图谱，不从目录或语义相似性推断边。构图按需执行，只在 Git 忽略的 `artifacts/graphs/` 写派生产物，不依赖判定缓存或回写知识卡。
64		70
65	## 为什么需要 Contract	71	## 为什么需要 Contract
66		72

Mgovernance/specs/skills.md+18-10

	@@ -10,7 +10,7 @@
10	\|---\|---\|---\|---\|	10	\|---\|---\|---\|---\|
11	\| `knowledge-query` \| 技术问题、decision、目标平台和可选范围条件 \| 实际覆盖、候选 OKF Concept 或 search/ready/outcome receipt \| 只读；只在调用方指定路径创建新审计产物 \|	11	\| `knowledge-query` \| 技术问题、decision、目标平台和可选范围条件 \| 实际覆盖、候选 OKF Concept 或 search/ready/outcome receipt \| 只读；只在调用方指定路径创建新审计产物 \|
12	\| `ascendc-api-knowledge-query` \| Ascend C API 问题、硬件平台和按需提供的本地 CANN 包路径 \| 经平台过滤和全文核验的 API 结论、相关卡片及头文件证据/缺口 \| 只读；检索和审计委托 Query \|	12	\| `ascendc-api-knowledge-query` \| Ascend C API 问题、硬件平台和按需提供的本地 CANN 包路径 \| 经平台过滤和全文核验的 API 结论、相关卡片及头文件证据/缺口 \| 只读；检索和审计委托 Query \|
13	-\| `knowledge-ingest` \| 固定来源、变化类型、目标路径、待表达结论和当前知识语料 \| 路由决策、候选 Concept、Git 来源账本；按需生成的 ignored 链接图谱和 API 引用建议 \| 可以创建候选卡；图谱和引用建议只读正文，产物不提交、不发布 \|	13	+\| `knowledge-ingest` \| 固定来源、变化类型、目标路径、待表达结论和当前知识语料 \| 路由决策、候选 Concept、Git 来源账本；按需生成且由 Git 忽略的链接图谱和 API 引用建议 \| 可以创建候选卡；图谱和引用建议只读正文，产物不提交、不发布 \|
14	\| `knowledge-lint` \| 单卡、完整知识仓或问题材料 \| 分级确定性 Finding 报告或可复现 Issue 草稿 \| 只读 \|	14	\| `knowledge-lint` \| 单卡、完整知识仓或问题材料 \| 分级确定性 Finding 报告或可复现 Issue 草稿 \| 只读 \|
15	\| `ops-knowledge-trace-ingest` \| 本仓可读的算子开发 trace、日志或已归一化事件流 \| 经证据门禁、独立审查、Lint 和检索验证的 Ascend C Runbook \| 只在本知识仓使用；只写经审查卡、导航和日志 \|	15	\| `ops-knowledge-trace-ingest` \| 本仓可读的算子开发 trace、日志或已归一化事件流 \| 经证据门禁、独立审查、Lint 和检索验证的 Ascend C Runbook \| 只在本知识仓使用；只写经审查卡、导航和日志 \|
16	\| `ops-knowledge-vv-ingest` \| 固定版本源码、唯一逻辑算子、入口、平台和独占目标文件 \| 不含可达 Cube/AIC 或 MIX_CV 节点的源码级 Operator 卡 \| 只写任务指定的最终卡 \|	16	\| `ops-knowledge-vv-ingest` \| 固定版本源码、唯一逻辑算子、入口、平台和独占目标文件 \| 不含可达 Cube/AIC 或 MIX_CV 节点的源码级 Operator 卡 \| 只写任务指定的最终卡 \|
	@@ -20,7 +20,7 @@
20		20
21	## Query	21	## Query
22		22
23	-Query 是 CANNBot Profile 的专用、确定性、只读 consumer。索引构建器先按统一 Contract 校验全部 Concept，再把卡片、词项、行数和指纹原子写入 ignored 的 `artifacts/indexes/`。日常 Query 只消费经过校验的持久化索引，并对卡片集合、时间戳和治理指纹执行 stale check；完整校验还会从知识卡重新推导 document/posting 行，并继续使用同一只读连接。索引缺失、损坏、查询表不一致或内容陈旧时失败关闭，不临时扫描全库或静默重建。	23	+Query 是 CANNBot Profile 的专用、确定性 consumer，不修改知识正文。索引构建器先按统一 Contract 校验全部 Concept，再把卡片、词项、行数和指纹原子写入 Git 忽略的 `artifacts/indexes/`。日常 Query 只消费经过校验的持久化索引，并对卡片集合、时间戳和治理指纹执行 stale check；完整校验还会从知识卡重新推导 document/posting 行，并继续使用同一只读连接。索引缺失、损坏、查询表不一致或内容陈旧时失败关闭，不临时扫描全库或静默重建。
24		24
25	它提供两类能力：	25	它提供两类能力：
26		26
	@@ -38,7 +38,7 @@ Query 是 CANNBot Profile 的专用、确定性、只读 consumer。索引构建
38	\| platform \| 普通搜索必须显式提供并包含全部目标平台；`agnostic` 卡可匹配任一已注册目标平台 \|	38	\| platform \| 普通搜索必须显式提供并包含全部目标平台；`agnostic` 卡可匹配任一已注册目标平台 \|
39	\| source/target technology \| 精确匹配 `Interoperability` 端点 \|	39	\| source/target technology \| 精确匹配 `Interoperability` 端点 \|
40		40
41	-Profile 过滤使用目录 ID，例如 `apis`；结果同时返回 OKF `type: API` 和 `profile: apis`。`platforms: []` 不能满足平台过滤；只有显式未定位 draft 查询才能返回。精确 API 名在目标平台 stable 查询零命中时，调用方必须另发一次不带 platform 的 `--include-unlocated --status draft` 查询，并把命中标为平台待核验候选，不能混入原平台结果或写进同一审计 receipt。Glossary 不携带平台字段，按平台中立术语处理。平台识别可在 `platforms` scope 中暂不传目标平台，其他搜索不得通过省略平台扩大范围。	41	+Profile 过滤使用目录 ID，例如 `apis`；结果同时返回 OKF `type: API` 和 `profile: apis`。`platforms: []` 不能满足平台过滤，只有显式请求未定位 `draft` 卡时才能返回。精确 API 名在目标平台 `stable` 查询零命中时，调用方必须另发一次不带 platform、限定 `draft` 且显式包含未定位卡的查询；命中只能标为平台待核验候选，不能混入原平台结果或写进同一审计 receipt。Glossary 不携带平台字段，按平台中立术语处理。平台识别可在 `platforms` scope 中暂不传目标平台，其他搜索不得通过省略平台扩大范围。
42		42
43	Query 当前不按 CANN 版本执行结构化过滤。卡片仍可记录 `cann_versions`，搜索结果仍可返回该字段；调用方读取正文后自行核对版本边界。	43	Query 当前不按 CANN 版本执行结构化过滤。卡片仍可记录 `cann_versions`，搜索结果仍可返回该字段；调用方读取正文后自行核对版本边界。
44		44
	@@ -50,7 +50,9 @@ Query 当前不按 CANN 版本执行结构化过滤。卡片仍可记录 `cann_v
50		50
51	较低信任层级会降权，但不构成访问控制。Agent 先依据脚本返回的路径、title 和 description 选择候选，再打开选中卡片的 `local_path` 阅读完整正文、范围和来源；读完后由 Agent 决定是否沿有效链接继续阅读相关知识或 include，不要求读取全部命中及链接。零命中只说明当前条件下未召回，不证明技术能力不存在。	51	较低信任层级会降权，但不构成访问控制。Agent 先依据脚本返回的路径、title 和 description 选择候选，再打开选中卡片的 `local_path` 阅读完整正文、范围和来源；读完后由 Agent 决定是否沿有效链接继续阅读相关知识或 include，不要求读取全部命中及链接。零命中只说明当前条件下未召回，不证明技术能力不存在。
52		52
53	-搜索输出绑定 schema、完整请求、canonical 请求指纹、语料/治理指纹、仓库状态、行数和卡片 SHA-256。复杂任务按 decision 原子保存不可覆盖 search receipt；随后冻结 retrieval state，要求每条 receipt 与 state 使用完全相同的目标平台集合，核对完整索引 provenance，并按原请求重放过滤、评分、排序和命中。在全部 decision covered 后生成绑定每个 search receipt 文件 SHA-256 的 ready receipt，并用 outcome manifest 将未被修改的检索链、目标平台实验及产物 SHA-256 绑定到原 decision。	53	+搜索输出绑定 schema、完整请求、canonical 请求指纹、语料/治理指纹、仓库状态、行数和卡片 SHA-256。复杂任务按 decision 原子保存不可覆盖的 search receipt；随后冻结 retrieval state，要求每条 receipt 与 state 使用完全相同的目标平台集合，核对完整索引 provenance，并按原请求重放过滤、评分、排序和命中。
		54	+
		55	+全部 decision covered 后生成绑定各 search receipt 文件 SHA-256 的 ready receipt，再由 outcome manifest 将未被修改的检索链、目标平台实验及产物 SHA-256 绑定到原 decision。
54		56
55	## Ascend C API 专用消费	57	## Ascend C API 专用消费
56		58
	@@ -84,13 +86,15 @@ Git Reference 批次使用 inventory、ledger 和不可覆盖 receipt；文档
84		86
85	API 引用建议仅在明确需要时扫描算子声明的固定提交源码，未恢复或被修改的 checkout 失败关闭。建议区分源码直接调用与仅有正文的示例，保留证据和歧义处理，但不回写卡片或直接生成边。图谱只消费最终正文链接，不扫描源码。	87	API 引用建议仅在明确需要时扫描算子声明的固定提交源码，未恢复或被修改的 checkout 失败关闭。建议区分源码直接调用与仅有正文的示例，保留证据和歧义处理，但不回写卡片或直接生成边。图谱只消费最终正文链接，不扫描源码。
86		88
87	-本地图谱按需从通过 Contract 的 Concept 之间的普通 Markdown 链接生成，节点只有知识卡，边只有有向 `links_to`。Index、外部 URL、固定本地源码、图片和代码示例不形成卡片间关系；孤立卡片可正常入库。图谱不依赖关系判定缓存或专用区块，JSON/HTML 只写入 ignored 目录，不回写正文。	89	+本地图谱按需从通过 Contract 的 Concept 之间的普通 Markdown 链接生成，节点只有知识卡，边只有有向 `links_to`。Index、外部 URL、固定本地源码、图片和代码示例不形成卡片间关系；孤立卡片可正常入库。图谱不依赖关系判定缓存或专用区块，JSON/HTML 只写入 Git 忽略的目录，不回写正文。
88		90
89	## Operator producer	91	## Operator producer
90		92
91	两项 Operator producer 处理通用 Ingest 无法用固定模板闭合的源码级 API/Host/Tiling/Kernel 事实。任务必须先冻结唯一逻辑算子、固定 Git Commit、入口类型、平台和目标文件；Skill 不自行改变调用层。当前正式 Operator 卡分别以 `aclnn` 承载公开 ACLNN/API 完整链路、以 `direct` 承载独立 Direct Invoke。仅有官方内部 Host/Tiling 入口的请求缺少对应已注册 call-mode，应报告分类缺口并 defer 写入，不能用已有目录冒充另一调用层。	93	两项 Operator producer 处理通用 Ingest 无法用固定模板闭合的源码级 API/Host/Tiling/Kernel 事实。任务必须先冻结唯一逻辑算子、固定 Git Commit、入口类型、平台和目标文件；Skill 不自行改变调用层。当前正式 Operator 卡分别以 `aclnn` 承载公开 ACLNN/API 完整链路、以 `direct` 承载独立 Direct Invoke。仅有官方内部 Host/Tiling 入口的请求缺少对应已注册 call-mode，应报告分类缺口并 defer 写入，不能用已有目录冒充另一调用层。
92		94
93	-分流只看目标范围内全部 Route 的 Host/launcher 可达 Device 节点：全部节点都不含 Cube/AIC 或 MIX_CV 时使用 VV；至少一个节点含 Cube/AIC 或 MIX_CV 时使用 CV。CV 算子的纯非 Cube Route 仍由同一 producer 闭合，不按单条 Route 拆分 Skill。SIMT、NDDMA、通信、Hybrid 和多 Kernel 本身不触发 CV。两项 Skill 都必须闭合公开入口或 launcher、Host selector、Tiling/POD、逐 Route Kernel、内存、同步、构建接线和固定来源；闭包或公开平台证据不足时停止写正式卡。	95	+分流只看目标范围内全部 Route 的 Host/launcher 可达 Device 节点：全部节点都不含 Cube/AIC 或 MIX_CV 时使用 VV；至少一个节点含 Cube/AIC 或 MIX_CV 时使用 CV。CV 算子的纯非 Cube Route 仍由同一 producer 闭合，不按单条 Route 拆分 Skill。SIMT、NDDMA、通信、Hybrid 和多 Kernel 本身不触发 CV。
		96	+
		97	+两项 Skill 都必须闭合公开入口或 launcher、Host selector、Tiling/POD、逐 Route Kernel、内存、同步、构建接线和固定来源；闭包或公开平台证据不足时停止写正式卡。
94		98
95	producer 一次只处理一个逻辑算子并只写任务指定的最终卡，不写 index、Registry、日志、图谱或中间账本，不执行编译、真机、数值或性能测试。外层贡献流程负责查重、导航、日志、Lint、索引和目标 Query。两项 producer 的固定标题、Frontmatter 和正文结构由各自模板定义。	99	producer 一次只处理一个逻辑算子并只写任务指定的最终卡，不写 index、Registry、日志、图谱或中间账本，不执行编译、真机、数值或性能测试。外层贡献流程负责查重、导航、日志、Lint、索引和目标 Query。两项 producer 的固定标题、Frontmatter 和正文结构由各自模板定义。
96		100
	@@ -107,13 +111,13 @@ Lint 是离线、只读、确定性的作者门禁，比 OKF 最小 conformance
107		111
108	单卡检查不覆盖父级索引和完整目录树；新增、删除或移动文件后必须执行全库检查。统一门禁启用严格来源导航，要求宽 Git tree 来源由同仓库、同 revision 的 blob 来源或正文链接定位。Lint 只确认链接目标和 Bundle 边界，不验证 Markdown 锚点。	112	单卡检查不覆盖父级索引和完整目录树；新增、删除或移动文件后必须执行全库检查。统一门禁启用严格来源导航，要求宽 Git tree 来源由同仓库、同 revision 的 blob 来源或正文链接定位。Lint 只确认链接目标和 Bundle 边界，不验证 Markdown 锚点。
109		113
110	-Lint 不联网检查 URL，不判断来源是否充分、正文是否正确、实验能否复现、shared 泛化是否合理或跨 DSL 是否等价。Registry 本地来源根不存在时不要求联网恢复；存在时才核对文档归档 URL 完成标记或 Git 固定提交、远程来源、干净工作区和被引用文件。Lint 固定执行自身版本的 Contract，目标根 Contract 不一致时失败，不导入目标根 Python。结构通过不等于结论正确。知识内容、检索、图谱、编译、治理或下游使用问题的材料整理也由 Lint 承载；它只生成本地 Issue 草稿和 `needs-info`，不会自行向外部系统提交。	114	+Lint 不联网检查 URL，不判断来源是否充分、正文是否正确、实验能否复现、shared 泛化是否合理或跨 DSL 是否等价。Registry 本地来源根不存在时不要求联网恢复；存在时才核对文档归档 URL 完成标记，或 Git 固定提交、远程来源、干净工作区和被引用文件。Lint 固定执行自身版本的 Contract，目标根 Contract 不一致时失败，不导入目标根 Python。结构通过不等于结论正确。知识内容、检索、图谱、编译、治理或下游使用问题的材料整理也由 Lint 承载；它只生成本地 Issue 草稿和 `needs-info`，不会自行向外部系统提交。
111		115
112	## 共同约束	116	## 共同约束
113		117
114	- 七项 Skill 共同遵守 `governance/schemas/` 和 `governance/contracts/`，不复制或放宽字段、路径和注册值。	118	- 七项 Skill 共同遵守 `governance/schemas/` 和 `governance/contracts/`，不复制或放宽字段、路径和注册值。
115	- 七项 Skill 的规范合同由 `SKILL.md` 的 `name`、`description` 和正文，以及按需加载的 `references/`、`templates/`、`scripts/` 等资源组成。其中六项可由安装器链接到业务项目，trace producer 保持仓内运行。规范源不保存 `agents/openai.yaml` 或其他单一 Agent 平台元数据。	119	- 七项 Skill 的规范合同由 `SKILL.md` 的 `name`、`description` 和正文，以及按需加载的 `references/`、`templates/`、`scripts/` 等资源组成。其中六项可由安装器链接到业务项目，trace producer 保持仓内运行。规范源不保存 `agents/openai.yaml` 或其他单一 Agent 平台元数据。
116	-- Query 和 Lint 始终只读；Ingest 不自动 commit、push、合并或发布。	120	+- Query 和 Lint 不修改知识正文或治理规则，只按调用方要求生成本地产物；Ingest 不自动 commit、push、合并或发布。
117	- CANN、DSL、API、算子、调试和优化事实进入 `knowledge/`，不埋在 Skill 指令中。	121	- CANN、DSL、API、算子、调试和优化事实进入 `knowledge/`，不埋在 Skill 指令中。
118	- 官方 reference 来源盘点与通用摄入路由属于 Ingest，仓内开发 trace 动态摄入属于 trace producer，源码级完整算子生产属于 VV/CV，Issue 材料整理属于 Lint。其他专用 producer 需要单独完成架构和发布评审。	122	- 官方 reference 来源盘点与通用摄入路由属于 Ingest，仓内开发 trace 动态摄入属于 trace producer，源码级完整算子生产属于 VV/CV，Issue 材料整理属于 Lint。其他专用 producer 需要单独完成架构和发布评审。
119		123
	@@ -124,8 +128,12 @@ Lint 不联网检查 URL，不判断来源是否充分、正文是否正确、
124	\| `consumer` \| `knowledge-query`、`ascendc-api-knowledge-query` \| 只读查阅和技术问答 \|	128	\| `consumer` \| `knowledge-query`、`ascendc-api-knowledge-query` \| 只读查阅和技术问答 \|
125	\| `contributor` \| 六项可安装 Skill（三项基础 + ascendc-api-knowledge-query + VV/CV） \| 贡献知识、治理规则或 Skill；不包含仓内 trace producer \|	129	\| `contributor` \| 六项可安装 Skill（三项基础 + ascendc-api-knowledge-query + VV/CV） \| 贡献知识、治理规则或 Skill；不包含仓内 trace producer \|
126		130
127	-知识仓安装入口把平台中立的规范源链接到目标项目 `.agents/skills/`，再在 Skill 目录之外创建客户端适配链接；默认恢复登记的文档和固定提交源码后准备索引（显式离线安装可跳过资源），写项目级知识根配置并维护 Agent 提示词入口。规范源依赖同一 checkout 的 Contract 与相邻 Skill；当前完整安装通过这些链接保留依赖，单独复制 Skill 目录不构成受支持的安装方式。知识根配置只选择数据位置，不提供缺失的脚本依赖，不复制 `knowledge/` 正文或修改用户全局配置。	131	+统一入口 `install.sh` 在远程执行时自动克隆或仅快进更新托管知识仓，并在更新前确认当前分支与请求分支一致；从已有本地 checkout 执行时则直接复用，不自动切换或更新分支。显式离线安装可以跳过仓库更新和资源恢复，也不校验远端 origin。
128		132
129	-项目提示词只维护领域任务的触发、入口路由和消费边界；具体平台识别、补搜、阅读、来源核对及审计规则由对应 Skill 维护，不在安装器中复制第二套检索工作流。	133	+安装器按仓内依赖清单补齐 Python 运行依赖，默认恢复登记的滚动文档归档和固定提交源码并准备索引。随后把平台中立的规范源链接到目标项目 `.agents/skills/`，在 Skill 目录之外创建客户端适配链接，写入项目级知识根配置，并维护 Agent 提示词入口。模式降级只移除安装器能够确认由自己创建的 Skill 链接，不覆盖用户路径。
		134	+
		135	+规范源依赖同一 checkout 的 Contract 与相邻 Skill；完整安装通过符号链接保留这些依赖，单独复制 Skill 目录并设置知识根不构成受支持的安装方式。知识根配置只选择数据位置，不补齐脚本依赖，也不复制 `knowledge/` 正文。除通过所选 Python 的 `pip` 安装声明的运行依赖外，安装器不修改 shell 启动文件或其他用户全局配置。
		136	+
		137	+项目提示词只维护领域任务的触发、入口路由和消费边界：用户已经提供唯一知识卡路径且问题只依赖该卡时可直接阅读全文；路径未知、需要多卡综合或出现新的证据缺口时进入 Query，Ascend C API 则进入同装的专用查询 Skill。具体平台识别、补搜、阅读、来源核对及审计规则由对应 Skill 维护，不在安装器中复制第二套检索工作流。
130		138
131	知识正文、机器规则、Contract 和 Skill 规范源都以本仓 Git commit 标识。	139	知识正文、机器规则、Contract 和 Skill 规范源都以本仓 Git commit 标识。

Rinit.sh→install.sh+491-52

Mlogs/2026-09-14.md+48-0

	@@ -1,5 +1,53 @@
1	# 2026-09-14	1	# 2026-09-14
2		2
		3	+## [21:03] governance \| 修复安装入口审查问题
		4	+
		5	+### Summary
		6	+
		7	+修复远程安装失败传播、模式降级残留、知识路径解析、客户端提示格式与权限、跨环境命令依赖、托管分支校验和 Python 运行依赖安装等问题，并补齐拒绝路径与跨客户端回归。
		8	+
		9	+### Details
		10	+
		11	+- 远程示例改为先完整下载临时安装器再执行，Raw 地址不可用时明确失败并提供本地克隆入口；`install.sh` 自动校验并补齐声明的 Python 运行依赖，更新已有托管仓前校验请求分支，显式离线 checkout 不再要求 origin。
		12	+- 从 `contributor` 切换到 `consumer` 时清理可确认由安装器创建的贡献类 Skill 链接，并同步已有托管客户端提示；提示中的单卡示例使用实际知识根，TRAE 规则带 `alwaysApply` Frontmatter，提示和项目环境配置更新均保留既有权限，其他客户端提示中的孤立 marker 也会在写入前拒绝。
		13	+- `get_resources.sh` 复用安装器选择的 Python，并以 Python 标准库替代 Bash 4 `readarray`、GNU `sha256sum` 和 `realpath` 依赖；安装指南同步说明前置条件、依赖安装、直接读卡、综合检索、离线更新及故障处理。
		14	+- 246 项评估回归通过（另有 1 项按环境跳过），全库 Knowledge Lint 检查 5,466 个 Markdown，P0/P1/P2 均为 0；Ruff、Shell 语法、差异空白和本次修改文档的 40 个本地链接检查通过。全库本地 Markdown 链接检查仍依赖未恢复的 ignored `cann-ops-raw` 固定源码快照，因此该单项未纳入本轮评估。
		15	+
		16	+## [17:23] docs \| 精简客户端支持说明
		17	+
		18	+### Summary
		19	+
		20	+安装指南只保留支持的客户端列表，不再承载兼容性核对过程、依据表格和验证说明。
		21	+
		22	+### Details
		23	+
		24	+- `docs/installation_and_usage.md` 保留 `codex`、`claude`、`opencode`、`trae`、`cursor` 和 `copilot` 六个安装器标识，删除客户端兼容性专节；安装器中已经校准的适配目录和回归保持不变。
		25	+- 2 项相关文档回归及差异空白检查通过。
		26	+
		27	+## [17:11] governance \| 校准安装器客户端兼容入口
		28	+
		29	+### Summary
		30	+
		31	+移除没有对应产品含义的 `agents` 安装器标识，并按六个客户端的公开约定校准 Skill 与持久指令落点。
		32	+
		33	+### Details
		34	+
		35	+- 安装与使用指南不再限定 Linux 或 macOS，改为直接声明 Bash、Git、网络和 Python 依赖；同时解释远程首次安装为什么需要先安装最小 Python 依赖，并新增六个客户端的目录、指令文件、官方依据和远程环境边界。
		36	+- `install.sh` 只接受 `codex`、`claude`、`opencode`、`trae`、`cursor` 和 `copilot`。TRAE 指令改写入 `.trae/rules/cannbot-knowledge.md`，Copilot 指令改写入 `.github/copilot-instructions.md`；Skill 入口继续使用各客户端公开支持的项目目录。
		37	+- 14 项安装器回归通过，覆盖六个客户端的安装、Skill 适配链接、指令安装/移除/重装和 `agents` 拒绝路径；2 项相关文档回归、Ruff、Shell 语法、修改文档本地链接及差异空白检查通过。全库 `knowledge-lint` 检查 5,466 个 Markdown，未发现问题。全库本地 Markdown 链接回归因 ignored 的 `cann-ops-raw` 固定源码快照未恢复而报告 1,322 个缺失目标，本次修改文档的本地链接已单独验证通过。
		38	+
		39	+## [16:34] governance \| 统一知识库安装与使用入口
		40	+
		41	+### Summary
		42	+
		43	+将根安装入口由 `init.sh` 统一为 `install.sh`，增加独立脚本自动克隆或仅快进更新知识仓的流程，并把安装、直接读卡和 Skill 检索方式集中到独立指南。
		44	+
		45	+### Details
		46	+
		47	+- `install.sh` 远程执行时默认管理 `$HOME/.cannbot/cannbot-knowledge`，也支持指定仓库位置、来源和分支；已有 checkout 只在 origin 匹配、已跟踪文件无修改且能快进时更新。本地仓内执行保持复用当前 checkout。后续资源恢复、索引准备、项目级环境配置、Skill 链接和托管提示流程保持统一顺序。
		48	+- README 移除分散的环境准备、安装和使用细节，改为导航到 `docs/installation_and_usage.md`。指南明确已知唯一知识卡时直接阅读全文；未知路径、多卡综合和复杂工程问题使用 `knowledge-query`；Ascend C API 使用同装的专用查询 Skill。
		49	+- 同步 Agent 约定、Skill 安装模式说明、算子开发 Recipe、统一 Shell 检查和文档引用；新增独立安装器 clone/fast-forward 回归与安装/使用文档契约。全库 `knowledge-lint` 检查 5,466 个 Markdown，P0/P1/P2 均为 0；13 项安装回归、3 项相关文档回归、6 项格式回归、1 项日志契约回归、修改 Python 的 Ruff、Shell 语法和差异空白检查通过。完整 `bash check.sh` 留待上库前执行。
		50	+
3	## [15:40] docs \| 精简历史日志并清理本地环境信息	51	## [15:40] docs \| 精简历史日志并清理本地环境信息
4		52
5	### Summary	53	### Summary

Alogs/2026-09-15.md+14-0

@@ -0,0 +1,14 @@
	1	+# 2026-09-15
	2	+
	3	+## [11:33] fix \| 修复安装模式降级的归属与原子性
	4	+
	5	+### Summary
	6	+
	7	+修复首次安装误删用户自建 Skill adapter、降级预检失败留下部分删除，以及 CRLF 提示文件未同步的问题。
	8	+
	9	+### Details
	10	+
	11	+- 清理未选 Skill 前先确认 canonical 链接来自当前知识仓；用户真实目录、指向其他来源的 canonical 链接及其 adapter 均保持不动。
	12	+- 模式降级先收集完整清理计划并统一校验归属、父目录和链接目标，全部通过后才删除；资源和索引准备完成后再次校验计划，避免预检后路径变化。
	13	+- 跨客户端提示 marker 改为复用提示更新逻辑的 LF/CRLF 行解析；新增首次 consumer 安装、清理预检失败零修改和 CRLF 跨客户端降级回归。
	14	+- 完整 `bash check.sh` 通过：264 项仓库测试、36 项 trace 测试和 29 个检索质量案例通过，全库检查 5,655 个 Markdown，P0/P1/P2 均为 0；Ruff、Shell 语法与差异空白检查通过。

Mrecipes/answer_with_evidence.md+3-3

	@@ -14,7 +14,7 @@
14	## 不适用场景	14	## 不适用场景
15		15
16	- 问题与 CANN 工程知识无关；	16	- 问题与 CANN 工程知识无关；
17	-- 目标是直接编写代码，而不是查询知识；	17	+- 任务只要求执行代码，不需要检索或引用知识；
18	- 目标技术或平台完全不明确；	18	- 目标技术或平台完全不明确；
19	- 索引不可用。	19	- 索引不可用。
20		20
	@@ -61,12 +61,12 @@
61		61
62	- 索引缺失、损坏或过期：停止查询，报告索引不可用。	62	- 索引缺失、损坏或过期：停止查询，报告索引不可用。
63	- 技术或平台无法确认：请求补充信息。	63	- 技术或平台无法确认：请求补充信息。
64	-- 当前范围没有结果：按[用户指南](../docs/user_guide.md#没有结果时怎么办)检查索引、覆盖情况和查询条件。	64	+- 当前范围没有结果：按[安装与使用指南](../docs/installation_and_usage.md#没有结果时怎么办)检查索引、覆盖情况和查询条件。
65	- 来源无法支持关键结论：说明证据不足。	65	- 来源无法支持关键结论：说明证据不足。
66	- 多张卡片在相同范围内互相冲突：保留冲突，不给出单一确定结论。	66	- 多张卡片在相同范围内互相冲突：保留冲突，不给出单一确定结论。
67		67
68	## 相关规则和延伸阅读	68	## 相关规则和延伸阅读
69		69
70	-- [知识库用户指南](../docs/user_guide.md)	70	+- [安装与使用指南](../docs/installation_and_usage.md)
71	- [`knowledge-query` Skill](../.agents/skills/knowledge-query/SKILL.md)	71	- [`knowledge-query` Skill](../.agents/skills/knowledge-query/SKILL.md)
72	- [Frontmatter 与证据](../governance/specs/frontmatter.md)	72	- [Frontmatter 与证据](../governance/specs/frontmatter.md)

Mrecipes/api_search.md+27-67

	@@ -1,36 +1,38 @@
1	-# 使用知识库查询 API	1	+# 使用知识库查询 Ascend C API
2		2
3	## 目标	3	## 目标
4		4
5	-通过已安装的 Ascend C API 查询 Skill，找到与目标硬件匹配的接口说明，并依据完整正文和来源回答问题。	5	+通过 Ascend C API 专用查询 Skill 找到与目标硬件匹配的接口说明，并依据完整正文和来源回答问题。
6		6
7	## 适用场景	7	## 适用场景
8		8
9	-- 开发AscendC算子（如 foreach_addcdiv_scalar、rms_norm）时需要确认 API 签名、参数含义或平台支持情况	9	+- 开发 Ascend C 算子时，需要确认 API 签名、参数、约束或平台支持情况；
10	-- 问题涉及具体开发硬件平台（910B/910B2/950 等）	10	+- 问题涉及明确的目标硬件平台；
11	-- 需要同时查看签名、参数、约束、示例和使用方法	11	+- 需要结合知识卡、相关卡片和本机头文件核对接口。
12		12
13	## 不适用场景	13	## 不适用场景
14		14
15	-- 知识库索引不可用；此时先恢复索引，不能把查询失败解释为 API 未收录。	15	+- 查询 ACLNN 接口或分析完整算子实现；这些场景使用 `knowledge-query`；
		16	+- 查询其他 DSL 的 API；
		17	+- 知识库索引不可用；此时应先恢复索引，不能把查询失败解释为 API 未收录。
16		18
17	## 前置条件与输入	19	## 前置条件与输入
18		20
19	-- 已由安装器或维护者准备的有效索引；当前采用字段加权的确定性词法检索。	21	+- 已由安装器或维护者准备的有效索引；
20	-- 明确的 API 名称和关键约束（如 `Div count 对齐`）	22	+- 明确的 API 名称或能力需求，以及需要核对的关键约束；
21	-- 目标平台标识（如 `a2`、`a3`、`950`）	23	+- 真实硬件型号或规范平台标识；
22	-- `knowledge-query` 与 `ascendc-api-knowledge-query` Skill 可用。	24	+- 同时可用的 `knowledge-query` 与 `ascendc-api-knowledge-query` Skill；
23	-- Ascend C 专用流程使用与 Query 同装的 `ascendc-api-knowledge-query`；需要本机头文件证据时提供当前工程的 CANN 版本和包路径，详细定位流程以该 Skill 为准。	25	+- 需要本机头文件证据时，提供当前工程的 CANN 版本和组件包路径。
24		26
25	## 步骤	27	## 步骤
26		28
27	-1. 明确问题。已知准确 API 名时先按该标识查询；只有能力需求时，用“实体 + 一个关键约束”描述问题。准备真实硬件型号和需要核对的条件。	29	+1. 明确问题。已知准确 API 名时按原标识查询；只有能力需求时，用“实体 + 一个关键约束”描述问题，同时给出真实硬件型号。
28	-2. 执行查询。使用 [`ascendc-api-knowledge-query`](../.agents/skills/ascendc-api-knowledge-query/SKILL.md)；它复用 Query 的平台过滤与匹配流程。参数和补搜规则由 Skill 维护。	30	+2. 执行查询。使用 [`ascendc-api-knowledge-query`](../.agents/skills/ascendc-api-knowledge-query/SKILL.md)。它复用 Query 的平台过滤和匹配能力，具体参数与补搜规则由 Skill 维护。
29	-3. 选择候选卡。根据标题、摘要、路径和状态选择要阅读的卡片。优先选择平台匹配、状态为 `stable` 的卡片。	31	+3. 选择并阅读全文。根据路径、标题、摘要和状态选择平台匹配的候选卡，再阅读完整正文；搜索摘要不能直接作为答案。
30	-4. 打开卡片正文。阅读完整保留的官方文档正文，包括签名、参数含义、约束条件、示例和平台范围；再沿正文中的普通链接查看相关算子设计卡，并核对目标卡中的调用证据。不要直接使用搜索摘要作答。	32	+4. 按需补充证据。正文不足时，再沿卡片链接阅读相关知识，或在用户提供的当前 CANN 组件包中核对头文件。头文件存在本身不能证明平台支持。
31	-5. 核对来源。确认来源确实支持准备采用的结论。如果多张卡片冲突，先比较它们的平台、版本和来源。	33	+5. 核对范围与来源。确认签名、参数、约束、平台和版本边界都能回到卡片正文及来源；多卡冲突时不直接选择其一。
32	-6. 补搜未定位卡。精确 API 名在目标平台的 stable 查询零命中时，按 Skill 单独补搜平台未定位的 draft 卡。此类结果只能提供待核验线索，必须阅读正文或来源确认平台；不能并入主查询的结果或共用审计凭据。	34	+6. 处理未定位候选。精确 API 名在目标平台的 `stable` 查询零命中时，按 Skill 单独补搜平台未定位的 `draft` 卡。此类结果只是待核验线索，不能并入原平台结果或共用审计凭据。
33	-7. 降级路径。未定位 draft 补搜仍未命中时，降级到官方来源核对原文。	35	+7. 报告缺口。补搜仍无结果时，说明查询范围和知识缺口；需要继续时再核对官方来源，不推断 API 不存在。
34		36
35	## 预期产物	37	## 预期产物
36		38
	@@ -44,63 +46,21 @@
44	仍需验证：<源码、实验或性能分析>	46	仍需验证：<源码、实验或性能分析>
45	```	47	```
46		48
47	-
48	-## 效果对比
49	-
50	-以下保留一组既有的内部对比记录：75 条来自算子开发的 API 查询，每个查询单独开会话，对比 docs-search 与 knowledge-query 的耗时、回合数、工具调用和 token 用量。当前仓库未附这批样本、逐条结果、运行配置和评判标准，因此这些汇总只作观察记录，不能作为可复现的效果保证。
51	-
52	-### 第一轮：deepseek-v4-flash
53	-
54	-\| 指标 \| docs-search（baseline） \| knowledge-query（本仓库提供的 skill ） \|
55	-\|---\|---\|---\|
56	-\| 平均耗时 \| 47.4s \| 32.6s \|
57	-\| 回合数 \| 7.8 \| 6.3 \|
58	-\| 工具调用 \| 11.2 \| 8.7 \|
59	-\| token/条 \| 33.5K \| 27.6K \|
60	-
61	-### 第二轮：glm-5.2
62	-
63	-\| 指标 \| docs-search（baseline） \| knowledge-query（本仓库提供的 skill ） \|
64	-\|---\|---\|---\|
65	-\| 平均耗时 \| 58.3s \| 44.9s \|
66	-\| 回合数 \| 7.7 \| 6.0 \|
67	-\| 工具调用 \| 11.2 \| 8.1 \|
68	-\| token/条 \| 33.3K \| 26.8K \|
69	-
70	-### 第三轮：minimax-m2.7
71	-
72	-\| 指标 \| docs-search（baseline） \| knowledge-query（本仓库提供的 skill ） \|
73	-\|---\|---\|---\|
74	-\| 平均耗时 \| 131.9s \| 69.3s \|
75	-\| 回合数 \| 9.2 \| 5.8 \|
76	-\| 工具调用 \| 10.2 \| 5.1 \|
77	-\| token/条 \| 56.1K \| 46.8K \|
78	-
79	-耗时可能受到测试时段、服务负载、工具版本和运行环境影响；缺少受控实验，不能据此比较模型能力或确定耗时变化的唯一原因。
80	-
81	-### 重合度分析
82	-
83	-原记录报告内容重合率超过 96%，但未提供计算方法和逐条对应关系。结果重合不能单独证明答案正确、召回完整或质量没有下降；需要公开样本、预期证据及逐条评判后才能评估这些指标。
84	-
85	-### 实验总结
86	-
87	-按表中已四舍五入的均值计算，三轮耗时分别降低约 31%、23%、47%；回合数分别减少 1.5、1.7、3.4；每条查询 token 分别减少 5.9K、6.5K、9.3K。若三轮样本等权，平均每条减少约 7.2K token。这些数字仅描述上表，实际任务的性能与答案质量仍需分别验证。
88	-
89	## 验证方式	49	## 验证方式
90		50
91	-- 命中卡的路径 Profile 是 `apis`，平台包含目标平台，生命周期满足当前查询条件。	51	+- 命中卡的路径 Profile 是 `apis`，平台包含目标平台，生命周期满足查询条件；
92	-- 正文中的签名、参数、约束和版本边界能分别回到 `sources` 核验。	52	+- 正文中的签名、参数、约束和版本边界能分别回到 `sources` 核验；
93	-- 使用仓库的检索回归验证代表性 API 查询。	53	+- 回答明确区分卡片原文、本机头文件证据和额外推断；
		54	+- 代表性 API 查询通过仓库检索回归。
94		55
95	## 失败或停止条件	56	## 失败或停止条件
96		57
97	-- 索引缺失、损坏或 stale：停止查询，请维护者重建索引。	58	+- 索引缺失、损坏或过期：停止查询，请维护者重建索引；
98	-- 目标平台 stable 查询和未定位 draft 补搜都零命中：报告知识缺口，不把它解释为 API 不存在。	59	+- 目标平台 `stable` 查询和未定位 `draft` 补搜都零命中：报告知识缺口，不把它解释为 API 不存在；
99	- 候选平台、版本或来源互相冲突：停止给出确定性结论，先核对固定来源或目标环境。	60	- 候选平台、版本或来源互相冲突：停止给出确定性结论，先核对固定来源或目标环境。
100		61
101	-
102	## 相关规则和延伸阅读	62	## 相关规则和延伸阅读
103		63
104	-- [知识库用户指南](../docs/user_guide.md)	64	+- [安装与使用指南](../docs/installation_and_usage.md)
105	- [`knowledge-query` Skill](../.agents/skills/knowledge-query/SKILL.md)	65	- [`knowledge-query` Skill](../.agents/skills/knowledge-query/SKILL.md)
106	- [`ascendc-api-knowledge-query` Skill](../.agents/skills/ascendc-api-knowledge-query/SKILL.md)	66	- [`ascendc-api-knowledge-query` Skill](../.agents/skills/ascendc-api-knowledge-query/SKILL.md)

Mrecipes/contribute_knowledge.md+1-1

	@@ -25,7 +25,7 @@
25	- 一条准备沉淀的工程结论；	25	- 一条准备沉淀的工程结论；
26	- 可以完整阅读和核对的来源；	26	- 可以完整阅读和核对的来源；
27	- 目标领域、技术、平台和必要的版本信息；	27	- 目标领域、技术、平台和必要的版本信息；
28	-- 已安装 contributor 能力和开发依赖；	28	+- 已安装 `contributor` 能力和开发依赖；
29	- 已检查工作区中的现有修改。	29	- 已检查工作区中的现有修改。
30		30
31	## 步骤	31	## 步骤

Mrecipes/operator_development.md+7-17

	@@ -18,7 +18,7 @@
18		18
19	## 前置条件与输入	19	## 前置条件与输入
20		20
21	-- Python 3.10 或更高版本，以及一个已存在的算子开发项目。	21	+- 已按安装指南准备好查询能力的算子开发项目。
22	- 算子名、输入输出、数据类型、布局、形状范围、精度要求和性能目标。	22	- 算子名、输入输出、数据类型、布局、形状范围、精度要求和性能目标。
23	- 已确认的目标硬件、Ascend C 技术路线、ACLNN 或 Direct 调用方式。	23	- 已确认的目标硬件、Ascend C 技术路线、ACLNN 或 Direct 调用方式。
24	- 工程实际使用的 CANN 版本和验证入口；排障任务还需首发错误、日志和当前实现。	24	- 工程实际使用的 CANN 版本和验证入口；排障任务还需首发错误、日志和当前实现。
	@@ -27,16 +27,7 @@
27		27
28	### 1. 安装到算子项目	28	### 1. 安装到算子项目
29		29
30	-在知识仓安装运行依赖，再安装 consumer Skill：	30	+按照[安装与使用指南](../docs/installation_and_usage.md#安装)，以 `consumer` 模式把知识库安装到已有算子项目。客户端选择、离线选项和资源恢复均以该指南为准。知识仓移动后应重新运行安装器；单独修改知识根变量不能修复失效的 Skill 链接。
31	-
32	-```bash
33	-git clone https://gitcode.com/cann/cannbot-knowledge.git
34	-cd cannbot-knowledge
35	-python3 -m pip install -r requirements.txt
36	-bash init.sh claude /path/to/operator-project consumer
37	-```
38	-
39	-客户端选择、离线安装和资源恢复见根 [README](../README.md#安装到项目)。安装器准备项目级 Skill 链接、配置、提示词及知识仓索引；目标项目路径必须已经存在。知识仓移动后需处理旧链接再重新安装，单独修改知识根变量不能修复失效的 Skill 链接。
40		31
41	### 2. 确认覆盖并检索	32	### 2. 确认覆盖并检索
42		33
	@@ -69,18 +60,17 @@ Ascend C API 使用 ascendc-api-knowledge-query 核对。
69	交付时报告知识依据、实际结果和未覆盖范围；来源不足或冲突时明确说明。	60	交付时报告知识依据、实际结果和未覆盖范围；来源不足或冲突时明确说明。
70	```	61	```
71		62
72	-### 4. 更新知识仓后重新准备索引	63	+### 4. 更新知识仓后刷新安装
73		64
74	-先保留本地未提交修改，确认分支，再更新并对同一项目重新运行安装器：	65	+从本地 checkout 安装时，先妥善处理未提交修改并确认分支，再更新仓库并对同一项目重新运行安装器：
75		66
76	```bash	67	```bash
77	cd /path/to/cannbot-knowledge	68	cd /path/to/cannbot-knowledge
78	git pull --ff-only	69	git pull --ff-only
79	-python3 -m pip install -r requirements.txt	70	+bash install.sh claude /path/to/operator-project consumer
80	-bash init.sh claude /path/to/operator-project consumer
81	```	71	```
82		72
83	-重新安装会准备索引并复用一致的链接。随后通过 Query 确认覆盖和目标查询正常；若来源与知识卡不一致导致准备失败，交由维护者按 Ingest 流程处理。资源下载成功或 Git 更新成功，都不代表查询索引已经可用。	73	+在线脚本或显式托管目录会在安全条件满足时自动快进，因此不需要手工执行上述 Git 更新。重新安装后，通过 Query 确认覆盖和目标查询正常；若来源与知识卡不一致导致准备失败，交由维护者按 Ingest 流程处理。资源下载或 Git 更新成功，都不代表查询索引已经可用。
84		74
85	## 预期产物	75	## 预期产物
86		76
	@@ -103,7 +93,7 @@ bash init.sh claude /path/to/operator-project consumer
103		93
104	## 延伸阅读	94	## 延伸阅读
105		95
106	-- [用户指南](../docs/user_guide.md)	96	+- [安装与使用指南](../docs/installation_and_usage.md)
107	- [形成可追溯回答](answer_with_evidence.md)	97	- [形成可追溯回答](answer_with_evidence.md)
108	- [使用知识库查询 API](api_search.md)	98	- [使用知识库查询 API](api_search.md)
109	- [贡献知识](contribute_knowledge.md)	99	- [贡献知识](contribute_knowledge.md)

	@@ -15,7 +15,7 @@ Frontmatter 保存检索、适用范围、生命周期和来源等结构化信
15	\| `description` \| 不打开正文也能理解的摘要 \| 非空 \|	15	\| `description` \| 不打开正文也能理解的摘要 \| 非空 \|
16	\| `tags` \| 工程任务和讨论主题 \| 2–6 个、不可重复，至少一个 `task.` 和一个 `topic.` \|	16	\| `tags` \| 工程任务和讨论主题 \| 2–6 个、不可重复，至少一个 `task.` 和一个 `topic.` \|
17	\| `status` \| 生命周期和默认查询可见性 \| `draft`、`stable` 或 `deprecated` \|	17	\| `status` \| 生命周期和默认查询可见性 \| `draft`、`stable` 或 `deprecated` \|
18	-\| `sources` \| 可回到原文或证据的入口 \| 数组；轨迹型 `Runbook` 可为空，其它非 `draft` 卡至少一项 \|	18	+\| `sources` \| 可回到原文或证据的入口 \| 数组；轨迹型 `Runbook` 可为空，其他非 `draft` 卡至少一项 \|
19	\| `created_at` \| 卡片首次形成时间 \| UTC RFC 3339 秒精度，以 `Z` 结尾 \|	19	\| `created_at` \| 卡片首次形成时间 \| UTC RFC 3339 秒精度，以 `Z` 结尾 \|
20	\| `updated_at` \| 最近一次实质变更时间 \| 同上，且不得早于 `created_at` \|	20	\| `updated_at` \| 最近一次实质变更时间 \| 同上，且不得早于 `created_at` \|
21		21
	@@ -103,7 +103,8 @@ sources:
103	- 除 `Runbook` 外，`stable` 和 `deprecated` 至少有一项来源，`draft` 可以使用 `sources: []`；	103	- 除 `Runbook` 外，`stable` 和 `deprecated` 至少有一项来源，`draft` 可以使用 `sources: []`；
104	- `resource` 接受 HTTP(S) URL 或已登记的本地来源；本地路径必须位于 Registry 登记的来源根目录中，不得是绝对路径、包含 `..`、反斜杠、查询参数或 fragment；Git 来源根可使用安全的多级相对路径，不能位于知识或治理设施目录中，也不能与其他来源根重叠；	104	- `resource` 接受 HTTP(S) URL 或已登记的本地来源；本地路径必须位于 Registry 登记的来源根目录中，不得是绝对路径、包含 `..`、反斜杠、查询参数或 fragment；Git 来源根可使用安全的多级相对路径，不能位于知识或治理设施目录中，也不能与其他来源根重叠；
105	- GitCode、GitHub、Gitee、GitLab、Bitbucket 和 Codeberg 上的文件、目录和 raw 来源必须固定到 40 位 commit，分支名和裸仓库首页不通过；GitCode/GitHub PR 与 Issue 可以直接使用对应仓库的规范工作项 URL，不要求 commit；	105	- GitCode、GitHub、Gitee、GitLab、Bitbucket 和 Codeberg 上的文件、目录和 raw 来源必须固定到 40 位 commit，分支名和裸仓库首页不通过；GitCode/GitHub PR 与 Issue 可以直接使用对应仓库的规范工作项 URL，不要求 commit；
106	-- Git 本地来源使用 `cann-ops-raw/ascendc/ops-nn/<40位commit>/<文件路径>` 等 Registry 登记路径，相对于知识仓根；四个算子仓统一放在 `cann-ops-raw/ascendc/<仓库名>/` 下。Registry 的 `repository` 与 `revisions` 保留远程来源和版本身份。统一获取入口按固定提交恢复，不跟随分支。正文源码链接相对于卡片目录，可带 `#L71` 或 `#L71-L80` 行号，仅作来源导航，不生成 Concept 或允许索引跳出 Bundle。已恢复 checkout 必须来源、提交、工作区一致，不能覆盖有本地修改的源码；原提交不存在的路径不得伪造或换版本，保留固定远程来源并报告缺口。	106	+- Git 本地来源使用 `cann-ops-raw/ascendc/ops-nn/<40位commit>/<文件路径>` 等 Registry 登记路径，相对于知识仓根；四个算子仓统一放在 `cann-ops-raw/ascendc/<仓库名>/` 下。Registry 的 `repository` 与 `revisions` 保留远程来源和版本身份，统一获取入口按固定提交恢复，不跟随分支；
		107	+- 正文源码链接相对于卡片目录，可带 `#L71` 或 `#L71-L80` 行号，仅作来源导航，不生成 Concept，也不允许索引跳出 Bundle。已恢复 checkout 必须来源、提交和工作区一致；不能覆盖有本地修改的源码，也不能为原提交中不存在的路径伪造或替换版本，此时应保留固定远程来源并报告缺口；
107	- 本地来源必须由仓库记录的获取流程提供；全库 Lint 要求获取脚本存在且可执行。当前 `cann-docs-raw/` 由 `get_resources.sh` 按 Registry 的 `archive_url` 恢复，并保持 Git 忽略；官方文档持续更新，不校验归档或内容树 SHA-256。本地根存在时，Lint 检查 `.complete` 的来源 URL 和被引用文件；	108	- 本地来源必须由仓库记录的获取流程提供；全库 Lint 要求获取脚本存在且可执行。当前 `cann-docs-raw/` 由 `get_resources.sh` 按 Registry 的 `archive_url` 恢复，并保持 Git 忽略；官方文档持续更新，不校验归档或内容树 SHA-256。本地根存在时，Lint 检查 `.complete` 的来源 URL 和被引用文件；
108	- Lint 不联网，也不判断来源是否支持结论；本地根尚未恢复时只检查注册路径形状。	109	- Lint 不联网，也不判断来源是否支持结论；本地根尚未恢复时只检查注册路径形状。
109		110
	@@ -165,4 +166,4 @@ source_headers:
165	- 文档归档 API 使用 `adv_api/`、`aicpu_api/`、`basic_api/`、`c_api/`、`simt_api/`、`tensor_api/`、`utils/` 下的公开 `.h` 路径，并统一补全 `include/` 前缀；路径不得含绝对路径、空段、`.`、`..` 或反斜杠。聚合兜底头（如 `kernel_operator.h`）不作为具体 API 的头文件定位信息。	166	- 文档归档 API 使用 `adv_api/`、`aicpu_api/`、`basic_api/`、`c_api/`、`simt_api/`、`tensor_api/`、`utils/` 下的公开 `.h` 路径，并统一补全 `include/` 前缀；路径不得含绝对路径、空段、`.`、`..` 或反斜杠。聚合兜底头（如 `kernel_operator.h`）不作为具体 API 的头文件定位信息。
166	- 值优先来自源文档正文的「头文件路径为：」声明与 `#include "..."`。缺少明确路径时，可依据固定版本源码审阅补充；必须区分声明与调用、注释及同名符号，不能仅凭符号出现位置判定声明头文件。	167	- 值优先来自源文档正文的「头文件路径为：」声明与 `#include "..."`。缺少明确路径时，可依据固定版本源码审阅补充；必须区分声明与调用、注释及同名符号，不能仅凭符号出现位置判定声明头文件。
167	- 文档归档不含 `include/` 源码树。重复同步从文档重算显式路径；没有显式路径时，保留同一 `primary` 文档来源卡片中已有的合法补充，不猜测新路径。归档校验仅验证这些补充的格式和来源绑定，不声称重新扫描或证明源码声明；来源版本升级时须重新审阅补充路径，路径字符串未变也不能视为已验证新版本。	168	- 文档归档不含 `include/` 源码树。重复同步从文档重算显式路径；没有显式路径时，保留同一 `primary` 文档来源卡片中已有的合法补充，不猜测新路径。归档校验仅验证这些补充的格式和来源绑定，不声称重新扫描或证明源码声明；来源版本升级时须重新审阅补充路径，路径字符串未变也不能视为已验证新版本。
168	-- 需单独链接的库文件（`.so`/`.a`）信息后续落地，当前不在该字段表达。	169	+- `source_headers` 不表达需要单独链接的库文件（`.so`/`.a`）。