UU AI Wiki
把普通资料整理为持久、可追溯、可直接用 Obsidian 或任意 Markdown 编辑器打开的专业知识库。
用户只需说出资料文件夹和目标；除非发生必须由用户处理的错误，不展示命令、依赖或实现细节。
用户体验
安装成功后只给一句引导：
> 你可以说：把我的资料文件夹变成专业 AI 知识库，或更新、查询、检查已有知识库。
将以下自然语言理解为完整工作流，而不是只执行其中一个脚本：
- “把
D:\资料变成知识库” - “更新这个知识库”
- “查询项目风险”
- “检查是否有矛盾、过期内容或失效链接”
- “在浏览器中打开知识库”
- “把这篇资料生成信息图”
安装
基础 Skill 不依赖第三方 Python 包。需要安装时，由智能体执行：
python "<Skill 目录>/scripts/install.py"
默认安装到当前用户的 Codex Skills。安装到团队项目：
python "<Skill 目录>/scripts/install.py" --project "<项目目录>"
只有安装器复检成功后才能确认安装成功。不要让非技术用户手工复制文件或运行 pip。
知识库边界
<知识库根目录>/
├── raw/ # 已归档的只读原始资料，按中文主题分类
│ ├── _inbox/ # 用户投递新增资料；成功同步后必须为空
│ └── 中文分类/
├── wiki/ # 智能体维护的 Markdown 页面，含置顶介绍页和图片集
│ ├── 中文分类/ # 按内容主题自动创建，不照搬文件夹结构
│ └── 图片集/ # 智能体按需创建和维护的信息图
├── .uu-ai-wiki/ # 入库状态和质量凭证
└── AGENTS.md # 长期维护规则
raw/_inbox/是唯一投递入口。智能体可以按文件名判断主题，将其中资料移动到
raw/<中文分类>/；内容重复时可以删除_inbox中的重复副本。成功后_inbox必须为空。- 除上述投递归档外，绝不编辑、重命名或删除
raw/中已经归档的文件。 .uu-ai-wiki/只保存确定性的跟踪状态，不保存文档转换副本或隔离运行环境。- 只引用
raw/...路径，并区分资料事实与智能体推断。 - 默认被动更新，不启动后台监听。
- 不创建数据库、向量库、Web 框架、包管理项目或 Git 仓库。
使用 Python 3.10 或更高版本运行脚本；路径始终加引号。所有 Markdown 按 UTF-8 处理；
Windows PowerShell 读取文件时显式使用 -Encoding utf8。
一键创建
用户指定的是普通资料文件夹时，默认直接在资料文件夹内创建 raw/、wiki/、
.uu-ai-wiki/ 和 AGENTS.md，不再新建旁置工作区；受支持的文档按原相对路径移入
raw/_inbox/ 投递箱，等待分类：
python "<Skill 目录>/scripts/wiki_tool.py" create "<资料文件夹>" --json
命令只移动受支持资料，不读取或转换 Office/PDF，也不创建虚拟环境或安装文档转换依赖。
JSON、YAML、Agent 文件和常见项目目录留在原位；raw/、wiki/ 或 .uu-ai-wiki/ 已存在时
拒绝覆盖。若没有 Python 3.10 或资料目录为空，说明一个清晰原因并停止，不留下伪成功结果。
用户明确要求保留原文件、在资料文件夹旁另建独立知识库目录时，增加 --output：
python "<Skill 目录>/scripts/wiki_tool.py" create "<资料文件夹>" --output "<知识库目录>" --json
该模式把可处理资料复制到 <知识库目录>/raw/_inbox/，原文件保持不变。
create 只完成安全初始化和资料投递，不直接扫描或生成 Wiki。随后必须继续执行
organize-inbox，把首次导入的源文件从 raw/_inbox/ 归档到 raw/<中文分类>/，再执行扫描
和“专业入库”。不能把资料进入 _inbox 称为知识库已经生成。新建或投递的资料默认都先放入
raw/_inbox/，不得直接放入 raw/ 的其他分类目录；只有 organize-inbox 能按中文分类把它们
归档到 raw/<中文分类>/。
更新已有知识库
用户指定已包含 .uu-ai-wiki/ 的目录时执行更新。未指定目录且当前目录不是知识库时，询问位置。
- 刷新受管理结构并确保
raw/_inbox/存在：
text
python "<Skill 目录>/scripts/wiki_tool.py" init "<知识库根目录>"
对从旧版本升级的知识库，先读取 status --json。如果 next_scan_mode 是 initial，在整理
_inbox 前运行一次 scan 建立初始清单；这是唯一允许遍历既有 raw/ 的迁移步骤。
init 会把遗留的根目录 inbox/ 或 raw/inbox/ 安全合并到 raw/_inbox/；不要同时保留
两个投递入口。
-
读取
raw/_inbox/中的文件名，为每个文件选择一个简短、稳定的中文主题分类。相同主题复用
已有分类，不按日期、格式或单篇文章创建一次性目录。只根据文件名无法可靠判断时，读取最少量
内容辅助判断。 -
一次性提交全部分类映射：
text
python "<Skill 目录>/scripts/wiki_tool.py" organize-inbox "<知识库根目录>" \
--assign "<_inbox 相对路径>=<中文分类>" --json
每个 _inbox 文件必须且只能映射一次。命令按 SHA-256 去重、处理同名冲突、移动新增资料并
删除投递箱中的重复副本；只有返回 inbox_empty: true 才能继续。不得手工绕过该命令移动资料。
- 仅在首次构建、旧知识库迁移或诊断资料问题时审计；正常
_inbox增量同步跳过本步骤，避免
重新遍历已归档资料：
text
python "<Skill 目录>/scripts/wiki_tool.py" audit "<知识库根目录>" --json
检查空文件、短文件、不支持格式、读取失败和需要 Agent 按需读取的二进制文档。短资料不是
自动失败，结合用户目标判断是否足以形成可靠知识。
- 扫描增量：
text
python "<Skill 目录>/scripts/wiki_tool.py" scan "<知识库根目录>" --json
正常更新只扫描本次投递队列，不重新遍历 raw/。旧知识库升级后的第一次扫描可以建立一次
初始清单；此后结果必须显示 scan_mode: incremental。只处理返回的 pending，不得重新读取
已入库来源或重新生成未受本次新增资料影响的 Wiki 页面。
-
读取
wiki/index.md、wiki/overview.md、wiki/questions.md、
wiki/knowledge-graph.md和wiki/log.md的最新内容。 -
逐项处理扫描结果：
add、update：文本资料直接读取prepared_path。delete：删除或限定只依赖该来源的结论。- PDF、DOC/DOCX、PPT/PPTX 和 XLS/XLSX 的
prepared_path仍是原始raw_path，
requires_agent_read为true；扫描脚本不会读取或转换它们。 - 保留原始
raw_path作为页面来源。
二进制文档按需读取规则
- 普通初始化、归档、审计和扫描不得转换 PDF 或 Office 文档，不得调用 MarkItDown、
pip、
包管理器或创建文档转换虚拟环境。 - 只有当前用户目标明确需要理解某份二进制文档的内容时，Agent 才读取该文件；例如用户明确要求
查询、总结或把该文档内容整合入 Wiki。不要仅因文件出现在扫描结果中就批量转换全部文档。 - 优先使用当前 Agent 环境已有的原生文档读取能力。确需中间格式时，由 Agent 在任务临时目录中
按需生成，不写入raw/、wiki/或.uu-ai-wiki/，也不把中间文件作为事实来源。 - 不得由本 Skill 的脚本安装或调用任何文档转换器。当前环境无法可靠读取时，保留原文件和待处理
状态，准确说明限制；不得凭文件名生成内容，也不得将其标记为已入库。 - 页面和日志始终引用原始
raw/...路径，不引用 Agent 的临时提取结果。
专业入库
不要按文件机械地产生孤立摘要。根据资料实际内容创建或更新：
- 来源页、主题页、实体页、概念页、方法页、规则页、场景页、对比页或综合页。
- 内容页必须位于单层的
wiki/<中文分类>/<页面>.md。分类由知识主题决定，可以与raw/分类
不同；复用已有稳定分类，只在确有新主题时创建目录，不建立更深层级。 - 同一稳定知识只保留一个主要页面；合并重复内容，保留已有有效综合结论。
- 概念回答“是什么”，方法回答“怎么做”，规则表达可验证规律，场景说明何时适用。
- 明确记录矛盾，并同时引用冲突双方；证据不足时不擅自裁决。
- 每个内容页提炼 1–5 个真实且可回答的问题。
- 更新总索引、概览、问题索引和小型 Mermaid 知识图谱。
- 向
wiki/log.md追加## [YYYY-MM-DD] ingest | ...。 - 增量更新可以补充现有页面、索引和交叉链接，但不得无差别重写或重建已有 Wiki；没有新增知识时
只记录去重结果，不创建重复页面。
内容页使用：
---
title: 页面标题
summary: 一句话说明
updated: YYYY-MM-DD
kind: concept
raw:
- raw/example.ext
questions:
- 这个概念是什么？
related:
- related-page.md
---
正文从 H2 开始。kind 只选择一个主要类型：
source、topic、entity、concept、method、rule、scenario、
comparison 或 synthesis。
强制质量闭环
所有 Wiki 页面、索引和来源回链完成后运行：
python "<Skill 目录>/scripts/wiki_tool.py" quality "<知识库根目录>" --json
必须修复全部 error。逐条审阅 warning，但不要为了清零而制造内容。质量检查会确认每个待入库
来源已被内容页引用，并生成与当前 Wiki 内容绑定的质量凭证。
只有凭证生成后才能确认入库：
python "<Skill 目录>/scripts/wiki_tool.py" mark-ingested "<知识库根目录>" --all
质量检查会拒绝非空的 raw/_inbox/，并确认每个新增来源至少由一个中文分类目录中的内容页承载。
质量检查后如果 Wiki 再次变化，凭证自动失效，必须重新检查。不得绕过 mark-ingested 的失败。
成功后向日志追加 ## [YYYY-MM-DD] quality | Wiki 质量检查，再用易懂中文总结处理资料、主要页面、
矛盾或失败，以及用户是否需要行动。新增、更新或首次创建的资料全部完成入库后，默认启动
“浏览器阅读”中的本地网页；只有用户明确要求不打开时才跳过。网页进程应在后台保持运行，
不得让启动命令阻塞结果回复。
查询与健康检查
查询时先读 wiki/questions.md 和 wiki/index.md，再读相关页面及其来源。回答提供 Wiki 页面和
原始资料路径。若形成值得长期保留的新综合结论，而用户未要求更新，先询问是否保存。
健康检查运行：
python "<Skill 目录>/scripts/wiki_tool.py" doctor "<知识库根目录>"
python "<Skill 目录>/scripts/wiki_tool.py" status "<知识库根目录>" --json
python "<Skill 目录>/scripts/wiki_tool.py" quality "<知识库根目录>" --json
再由智能体检查语义矛盾、过期结论、孤立页面、重复实体和无来源结论。不要修改原始资料。
可选能力
浏览器阅读
只有用户要求浏览时才需要 Node.js 20 或更高版本：
node "<Skill 目录>/scripts/wiki_viewer.mjs" "<知识库根目录>"
该服务只监听 127.0.0.1，只读展示 wiki/、raw/ 和图片，不修改知识库。PDF 使用浏览器
原生预览；Office 文档保留为原文件入口，不读取 Agent 的临时中间结果。
页面根据文件路径自动生成多级可折叠目录，左右区域独立滚动；新增子目录后刷新即可出现。
介绍页固定显示在 Wiki 目录首位；“图片集”和“wiki配置”作为同级栏目固定显示在
“wiki知识库”末尾，索引、概览、问题索引、知识图谱和日志统一收纳在默认折叠的
“wiki配置”栏目中。
导入钉钉文档
该能力桥接用户已经安装并完成授权的 DingTalk Workspace CLI（DWS）。不实现安装、登录或
授权状态机。
Agent 入口：
- 用
dws doc +search --limit 30 --format json获取最近访问文档；搜索关键词时增加
--query "<关键词>"。直接解析完整 JSON 的documents数组，不使用 NDJSON。 - 搜索结果默认都用
dws doc read --node "<nodeId>" --content-format markdown --format json读取 Markdown。 - 只读取返回对象顶层或
result中明确的markdown字段；移除 DWS 生成的展示性
<span>标签，并写入含钉钉标题、nodeId和来源 URL 的 frontmatter，再保存为 UTF-8
.md。用户指定目录时必须位于wiki/内；未指定时导入到当前 Wiki 文档所在目录。 - 将 Markdown 中的钉钉 OSS 图片下载到
wiki/图片集/钉钉/<文档名>/，把临时签名 URL
改写为相对路径；图片下载失败时不得把文档报告为下载成功。 - 首次下载不覆盖同名文件；搜索结果发现目标文件已存在时显示“已下载”和“重新下载”，只有用户
点击“重新下载”才覆盖该目标。
浏览器入口：
- 打开“钉钉文档”窗口时立即加载最近访问的 30 篇文档；搜索框为空时重新加载最近访问文档。
- 结果显示名称、类型和修改时间；默认操作统一为“下载 Markdown”。
- 下载成功后显示显眼的成功提示，并将该项标记为“已下载”；后续可点击“重新下载”更新本地副本。
- 导入目录取当前正在浏览的
wiki/文档目录；当前是raw/文档或尚未选择文档时使用
wiki/根目录。服务端校验目标范围并拒绝覆盖同名文件。 - 页面只监听
127.0.0.1，命令参数不经过 shell。空结果与 DWS 调用失败必须分别显示。 - 这是把远端 Markdown 复制为 Wiki 页面，不自动执行专业入库或标记来源已入库；需要知识整合时，
再按“更新已有知识库”与“强制质量闭环”处理。
文档生成信息图
只有用户要求生成图片时，完整读取
references/visualization.md 和
references/infographic-prompt.md。
基础知识库流程不依赖图片工具或图片 API。
企业扩展
只有任务确实需要 UUOA 或钉钉工作区时，读取
references/extensions.md 并检查对应扩展。
任何可选扩展缺失都不得阻塞基础 Wiki 工作。
自检
修改 Skill 后运行零第三方依赖的核心回归测试：
python -B "<Skill 目录>/scripts/self_test.py"
自检会清理 Skill 目录中仅供 Python 加速的 __pycache__/ 和 .pyc，避免 SkillHub
直接上传文件夹时把二进制缓存识别为不支持文件；这些缓存不属于 Skill 能力。
