Page Title

Source:

Content here. Cross-reference related pages with markdown links: Related Page

Key Points

• ...

Related

• Page A — how it relates
• Page B — how it relates

两条配套约束值得注意：

- **`> Source:` 溯源行**：记录知识出处（URL、文档名、对话等），素材有明确来源时必须包含。这让每一条沉淀知识都可回溯，也方便日后核对与更新。
- **只链接已存在的页面**：若某个概念值得单独立页，先创建页面、再加链接。这一约束保证了交叉引用不产生悬空链接。

这些 markdown 链接不是摆设——Web 控制台的知识图谱可视化就依赖它。[service.py](https://gitcode.com/GitHub_Trending/ch/CowAgent/blob/c06921587121e87d126a5fb4dd1ab03d9fae3b96/agent/knowledge/service.py?utm_source=gitcode_repo_files#L525-L589) 的 `build_graph` 用正则 `\[([^\]]*)\]\(([^)#]+\.md)(?:#[^)]*)?\)` 遍历所有页面，提取指向 `.md` 的相对链接（忽略 `#` 锚点、跳过外部 `://` 链接、对百分号编码做 `unquote` 解码），与页面自身构成节点，两端都有效的边才保留并去重，最终输出 `{nodes, links}` 供前端渲染知识图谱。也就是说，"页面间用相对路径互链"这条写作规范直接决定了知识图谱的连通性。

## index.md 与 log.md 的维护规范

### 索引格式

`knowledge/index.md` 采用按分类分组的扁平列表，每行一个页面：

```markdown
# Knowledge Index

## Category A
- Page Title — one-line summary

## Category B
- Page Title — one-line summary

规范要求：Title — 一句话摘要 的单行格式，按子目录分组，不用表格、不用 emoji；分类命名与结构保持灵活，沿用索引中已有的组织方式即可。由于该索引会被整段注入系统提示，简洁的单行格式能显著节省上下文预算。

此外，KnowledgeService 提供了自动化的"索引修复"能力：rebuild_index_md 会扫描 knowledge/ 实际目录树，从每个 Markdown 文件的前 20 行提取 H1 标题（缺省用文件名兜底），按顶层目录分组重新生成 index.md，并对路径段做百分号编码以保证含空格的链接合法。这意味着即使 Agent 漏更新了索引，管理接口也可以从磁盘事实重建，避免索引与实际文件漂移。index.md 与 log.md 在 PROTECTED_FILES 中被列为受保护文件，任何通过服务接口的删除、改写操作都会被拒绝，确保两个"骨架文件"不会被意外破坏。

日志格式

knowledge/log.md 是仅追加文件，新条目始终加在底部：

## [YYYY-MM-DD] ingest | Page Title
## [YYYY-MM-DD] synthesize | Page Title