AI-Brain/AI-LLM-Wiki/AGENTS.md

AI-LLM-Wiki Agent Rules

本文件是本仓库中 LLM/Codex 的最高层工作约定。目标是维护一个“原始资料不可变、Wiki 可重复编译、结论可回溯”的知识库，而不是按文件夹收藏孤立摘要。

1. 系统目标

• 将 raw/ 中的真实资料编译为 wiki/ 中相互连接、持续演化的知识页面。
• 优先更新已有概念、实体、主题和综合分析，而不是为每份资料机械创建一篇摘要。
• 让 Wiki 中每个重要事实、数字、引文和判断都能回到具体原始文件与定位信息。
• 区分“来源陈述”“Wiki 综合判断”和“未知/待验证”，不得用模型常识填补证据空白。
• 仅在有真实资料支撑时扩充知识层；当前资料不足时保持页面缺失或明确标记待验证。

2. 目录职责

路径	职责
raw/inbox/	尚未归档的新原始资料入口。完成 ingest 后可复制到合适的 raw 分类，但不得改写原件。
raw/articles/	文章、博客、访谈文字稿等原始资料。
raw/papers/	论文、技术报告及其原始附件。
raw/company-docs/	公司官方文档、产品文档、公告、发布说明。
raw/videos/	视频、音频或忠实转录稿；引用时带时间戳。
raw/assets/	图片、图表、数据附件及其他支持文件。
wiki/concepts/	可跨来源复用的概念、机制和方法。
wiki/entities/	公司、组织、人物、模型、产品等实体。
wiki/topics/	围绕问题或领域组织的主题导航与现状页。
wiki/sources/	来源的书目信息、可靠性、覆盖范围及与 Wiki 页面的关系；不是孤立摘要仓库。
wiki/syntheses/	跨多个来源形成的比较、趋势、争议和综合判断。
wiki/index.md	全部 Wiki 页面的注册表，记录路径和一句话说明。
wiki/log.md	ingest、query、lint 操作的只追加审计日志。
output/	面向外部的文章、报告和脚本等产物，不是事实来源。
legacy-notes/	重构前内容的只读备份，不自动视为已验证资料。

3. 文件修改权限

区域	允许	禁止
raw/	摄入新的原始文件；读取；计算校验值	修改、缩写、格式化、覆盖、删除、移动或重命名已存在文件
wiki/	基于证据新建、更新、重构和交叉链接页面	无来源生成事实；删除仍被引用的证据说明
wiki/log.md	仅在文件末尾追加新记录	修改、排序、压缩或删除既有记录
output/	创建和修改对外产物	将 output 文件引用为事实证据
legacy-notes/	读取、人工审查、按需复制内容到 raw/ 作为待验证输入	原地修改或删除；直接当作已验证事实来源
AGENTS.md、README.md	架构或规则变更时更新	在普通 ingest/query 中随意改写规则

若 raw 文件错误或过期，不修改原件：新增更正资料，并在相关 Wiki 页面中并列说明。文件名冲突时保留两份，给新文件增加稳定的来源或短哈希后缀，绝不覆盖。

4. Ingest 流程

1. 登记输入：确认资料来自真实来源，记录标题、作者/机构、发布日期、原始 URL（如有）、获取日期、文件路径和 SHA-256。网页资料应同时保存可复核的原始快照；元数据或转录稿必须另存为独立文件，不得改写原件。
2. 保持原样：把原文件写入合适的 raw/ 分类。若先进入 raw/inbox/，后续归档使用复制而非移动，并保留 inbox 原件；任何文本清洗或转录衍生物都作为新文件保存。
3. 检查重复：按来源、标题、日期和 SHA-256 识别完全重复或不同版本。完全相同的文件不重复摄入；内容不同的版本分别保留，不得静默覆盖。
4. 阅读与拆解：提取资料实际支持的实体、概念、主张、数据、时间范围、假设、限制和冲突点。
5. 检索现有 Wiki：先读 wiki/index.md，再搜索相关页面和反向链接，决定更新旧页还是新建页面。
6. 设计变更集：优先更新多个既有知识节点及其连接。只有当资料本身值得独立登记时才创建 wiki/sources/ 页面；不得用“一份资料 = 一篇孤立摘要”代替知识整合。
7. 写入 Wiki：区分来源陈述与综合推断；给重要结论添加 raw 文件引用和精确定位；补充双向相关链接。
8. 更新索引：新建、重命名、移动或显著改变页面用途后，同步更新 wiki/index.md。
9. 追加日志：在 wiki/log.md 末尾追加一条 ingest 记录，列出新增 raw 文件及 SHA-256、受影响 Wiki 页面、操作结果和未解决问题。
10. 运行 Lint：完成结构、链接、引用、索引和 raw 不可变性检查；只修复允许修改的区域。

5. Query 流程

1. 从 wiki/index.md 定位可能相关的概念、实体、主题和综合页。
2. 沿页面的 related 和正文链接扩展上下文；对关键结论打开所引 raw 文件核验，不只依赖 Wiki 转述。
3. 区分已有证据、跨来源推断、冲突信息和证据缺口；不确定内容明确写“待验证”。
4. 回答时提供对应 raw 路径与定位信息。若只找到 output 或 legacy 内容，说明它不能作为事实依据。
5. Query 默认不扩写 Wiki；只有用户明确要求沉淀，或 query 同时属于 ingest/维护任务时，才按 Ingest 流程更新页面。
6. 在 wiki/log.md 末尾追加 query 记录，写明问题摘要、读取页面/来源和结果状态；不得记录密码、Token 或敏感原文。

6. Lint 流程

Lint 是知识库一致性检查，不生成新的百科内容。每次检查至少覆盖：

1. raw/ 中已有文件是否被修改、覆盖、移动、重命名或删除；发现问题只报告，不自动改写原件。
2. Wiki 普通页面的 Frontmatter 必填字段、枚举值和日期格式是否有效。
3. 内部链接与 raw 引用目标是否存在，定位信息是否足够精确。
4. 重要事实、数字、引语和争议性结论是否至少有一个 raw 来源。
5. wiki/index.md 是否覆盖所有 Wiki 页面，路径和一句话说明是否与实际一致。
6. 是否存在无入口、无相关链接或仅复述单一来源的孤立页面。
7. wiki/log.md 是否保持只追加，日志字段是否完整。
8. output/ 或 legacy-notes/ 是否被错误用作事实来源。

Lint 可修复 Wiki 的格式、失效链接和索引遗漏；涉及事实含义、来源冲突或 raw 完整性时只报告并请求人工判断。结束后在日志末尾追加 lint 记录，写明范围、问题数量、修复数量和遗留项。

7. Wiki 页面格式

wiki/index.md 与 wiki/log.md 使用各自的专用格式。其他 Wiki 页面使用 UTF-8 Markdown，并至少包含：

---
title: 页面标题
page_type: concept | entity | topic | source | synthesis
status: seed | growing | stable | disputed
created: YYYY-MM-DD
updated: YYYY-MM-DD
aliases: []
related: []
raw_sources: []
---

正文推荐结构如下；没有证据的章节应省略，不得为了完整外观而填充空话：

# 页面标题

> 一句话定义或本页结论，并标明适用范围。

## 核心内容

将可核验事实与 Wiki 综合判断分开表达，每个重要结论就近引用。

## 争议与限制

记录来源冲突、适用条件、时间范围和待验证问题。

## 相关页面

- [相关页面](../对应目录/页面名.md)

• concept：解释稳定概念、机制、边界和相关概念。
• entity：记录实体身份、时间敏感属性及其与主题的关系。
• topic：组织一个问题空间，连接多个概念、实体、来源和综合页。
• source：记录来源元数据、证据价值、局限及被哪些页面使用，不做孤立全文摘要。
• synthesis：明确列出所综合的多个来源，区分证据与推断。

更新正文时必须更新 updated；新建页面时同步登记 index。不得预先批量创建没有资料支撑的占位知识页。

8. 引用规范

• 事实来源只能指向 raw/；外部 URL 可作为元数据补充，但不能替代已摄入的 raw 文件。
• 页面正文使用就近引用。由于内容页都位于 wiki/ 的一级子目录，推荐格式：[来源：标题，定位](../../raw/articles/文件名.md)。
• 定位必须尽可能具体：Markdown 用章节名/段落标识，PDF 用页码，视频用时间戳，数据用表名/行列或记录 ID。
• 示例：该版本新增某能力。[来源：发布说明，“Features”](../../raw/company-docs/2026-01-01-example-release.md)
• 同一句包含多个独立主张时拆分并分别引用；综合结论应引用所有关键来源。
• 不引用 output/；legacy-notes/ 需先作为真实资料摄入 raw，完成核验后才能引用。
• 转述应保持原意；直接引语使用引号并标注精确位置，不把推断伪装成来源原话。
• 对容易混淆的内容显式使用三类标签：来源陈述（来源直接支持）、Wiki 综合判断（基于多个来源的推断）、待验证（证据不足）。标签不能替代引用。

9. 页面命名规范

• 文件名表达稳定、单一、可搜索的主题，扩展名统一为 .md。
• 英文名称使用小写 kebab-case；中文名称使用简洁的常用名，不加空格、序号或分类前缀。
• 实体页优先使用官方常用名；同名时增加最小必要限定词，例如 mercury-model.md 与 mercury-company.md。
• 概念页用名词或名词短语；主题页用领域/问题名；综合页用能表达比较或结论范围的名称。
• 来源页建议使用 YYYY-MM-DD-来源-短标题.md；未知日期不得编造，可使用 undated-来源-短标题.md。
• 不用 新建文档、总结、资料1 等临时名称。页面重命名必须同时更新全部链接、index 和 log。

10. 冲突信息处理

1. 不用新资料静默覆盖旧结论，也不以模型判断直接宣布某方正确。
2. 并列记录各主张，分别引用 raw，注明作者/机构、发布日期、资料版本、适用范围和定义差异。
3. 优先检查冲突是否来自时间变化、口径、样本、方法、产品版本或一手/二手来源差异。
4. 可依据明确标准给出带条件的综合判断，并标记为“Wiki 综合判断”；说明标准和推理链。
5. 证据不足时将页面状态设为 disputed 或在正文标记“待验证”，列出需要补充的资料。
6. 后续解决冲突时保留历史背景与旧来源，不删除曾经真实存在的不同说法。

11. wiki/index.md 更新规则

• index 必须登记包括 index.md 自身和 log.md 在内的所有 Wiki Markdown 页面。
• 每行至少包含 page_type、仓库相对路径、页面标题、一句话说明、状态和更新时间。
• 一句话说明描述页面实际覆盖范围，不复制空泛标题，不写没有证据的结论。
• 新建、移动、重命名、归档页面或显著改变页面职责时，在同一变更中更新 index。
• 条目按 page_type，再按路径稳定排序；不得保留指向不存在文件的条目。
• index 是注册表和入口，不承载正文知识结论。

12. wiki/log.md 追加规则

• 只允许在文件末尾追加；旧记录即使有误也不得修改，应追加 correction 记录说明所更正的日志 ID。
• 时间使用带时区的 ISO 8601，例如 2026-07-17T14:30:00+08:00。
• 每条日志使用唯一 ID：YYYYMMDD-HHMMSS+0800-operation；同秒冲突时添加两位序号。
• 必填字段：operation（ingest、query、lint 或 correction）、summary、inputs、wiki_changes、result、open_issues。
• inputs 对 ingest 列 raw 路径和 SHA-256，对 query 列问题摘要及核验来源，对 lint 列检查范围。
• 不把完整知识正文塞入日志，不记录秘密信息，不将日志当作事实来源。

13. 操作完成门槛

• Ingest 完成：raw 文件存在且哈希已记录；受影响页面已更新；重要结论引用可解析；index 已同步；ingest 与 lint 日志均已追加。
• Query 完成：关键回答已回查 raw；证据、推断、冲突与未知已区分；引用带定位；query 日志已追加。
• Lint 完成：已报告检查范围、问题数、修复数和遗留项；未自动改写 raw 或替人裁决事实冲突；lint 日志已追加。
• 任一必需步骤未完成时，result 只能记为 partial 或 failed，不得记为 success。