Project Knowledge Writer
将项目源码逐文件分析并写成 Obsidian 风格的知识文档，为项目生成"阅读理解/开发" skill，并按"功能描述"规范处理新增/修改功能。
输入确认
开始前，向用户确认（可合理默认，无需每个都追问）：
文档保存路径—— 项目分析文档（.md）所在/目标目录。
- 若位于当前可写工作区之外，需先请求写入授权，授权通过前不要写。项目路径—— 待分析/补充依据的源码根目录。
- 增量/功能分析模式下必须与用户确认项目路径。运行模式—— 判定见下节：
- 全量：文档目录为空或不存在既有分析文档。
- 增量：文档目录已存在本项目分析文档。是否生成开发 skill—— 是否生成本项目"阅读理解/开发" skill，及存放目录（默认$ACODE_HOME/skills）。是否需要处理功能描述—— 是否执行功能分析（默认执行，见阶段三）。工具检查—— 见下节。
运行模式判定
- 查看
文档保存路径下是否已存在本项目分析文档（如项目总览.md、<模块>/xxx.c.md）。 - 存在 → 增量；不存在/为空 → 全量。
- 向用户确认项目路径与判定结果后再动手。
工具检查
分析前检查本次任务需要的外部工具是否可用（按需）：
rg/ 系统grep（或等价的文件检索能力）—— 列文件、搜函数签名/结构体定义、核验 [[]] 链接标题。python3—— 仅在需要跑脚本/模板（如 skill-creator 的 init_skill.py）。- 文档读写与检索能力（文件 read/write/edit、glob、grep）与目标是否 Obsidian 笔记库。
- 编译/测试工具链（在生成开发 skill 与功能分析验收阶段检查）。
流程：
1. 用 Get-Command/which 或等价方式探测所需命令。
2. 若某项必需工具缺失：先停手，把缺失项和它对本次任务的影响告诉用户，并问"是否自动安装"；得到允许再安装，否则给出替代做法后继续。
3. 记录工具检查结论，写进最终报告。
输出规范（核心约定）
- 每个源文件一篇
.md，命名<文件名>.md；入口文件用<文件名>, 应用入口.md。 - 每篇以
# 文件路径开头，标注源文件路径。 - 函数、结构体、枚举、全局变量都单独用一个
# 名称...()或# 名称...结构/枚举标题描述其作用。 - 引用这些实体的地方一律用 Obsidian 双向链接：跨文件
[[目标文件名#实体标题]]、同文件[[#实体标题]]。 - 流程性说明用缩进列表；中文描述。
- 完整格式与示例见 [[references/conventions.md|文档规范]]。
阶段一·全量：从源码生成分析文档
按"先盘点、后逐模块、再索引"推进：
- 盘点范围：列出项目根目录与关键子目录，识别"项目自有代码"vs"基线SDK"；与用户确认边界；统计每个模块
.c/.h数量。 - 逐模块分析：每文件先读头文件（结构体/枚举/API），再读
.c函数清单与关键函数体；预编译库按其对外头文件接口说明。 - 生成文档：每个文件一篇
.md（遵循 [[references/conventions.md|文档规范]]），模块子目录镜像源码，写项目总览做索引。 - 验收：实体
#标题完整、[[目标#标题]]目标标题确实存在（grep 核验）、中文与链接完好、交付文件数符合清单。
阶段一·增量：理解既有文档并补充优化
用于文档保存路径已存在本项目分析文档的场景。不做全量重建：
- 理解既有文档：读项目总览与各模块，识别实体
#标题、规范版本、覆盖范围与空缺。 - 确认项目路径（增量下必确认）。
- 增量补充：以当前源码为准校准实体标题、
[[]]链接、描述；补齐未覆盖模块/缺失标题/过时描述；必要时更新项目总览。 - 验收：与全量相同。
阶段二：生成项目开发 skill（阅读理解）
在分析文档（全量或增量）验收通过后，为项目生成"阅读理解/开发" skill，支持阅读、修改、编译、测试。
- 确认工具链：识别构建方式与编译/测试命令、产物路径；探测工具链可用性，缺失项报告并问是否自动安装。
- 盘点项目特定信息：项目路径、分析文档路径、入口与关键模块、编译与测试命令、产物与验收。
- 按 skill-creator 规范创建
<项目名>-dev（默认$ACODE_HOME/skills），SKILL.md 按 [[references/reader-skill-template.md|开发 skill 模板]] 填充，写明分析文档路径、编译/测试命令。 - 验证：校验新 skill 的 frontmatter/命名（
quick_validate.py，其依赖pyyaml，缺失按工具检查流程处理）；确认能定位分析文档与构建/测试命令。
阶段三：功能分析
按 [[references/feature-analysis.md|功能分析规范]] 管理功能描述。
- 确保文档根目录下存在
功能描述/子目录；若刚创建，先播种两个模板（新增需求的功能模板.md、需要修改的功能模板.md）。 - 扫描
功能描述/中标注为「新增需求的功能」或「需要修改的功能」的功能文件（排除模板）。 - 无待办 → 跳过；有则逐文件：
- 读该功能文件各段落（需求/修改内容/涉及模块/验收标准）；
- 按其描述实现或修改（结合分析文档与源码）；
- 按验收标准测试（可编译时用开发 skill 的编译/测试流程）；
- 测试通过 → 向用户汇报并提请确认版本号；
- 用户确认后 → 按生命周期转「现有功能」并写入版本号（新增需求→1.0.0；需要修改→用户确认版本号），内容转为现有功能规范；
- 测试不通过或需求不明确 → 停下说明并等待，不擅自转现有。 - 涉及结构体/枚举/函数签名变更时，同步更新对应分析文档。
资源
references/conventions.md—— 项目分析文档的格式规范与示例（阶段一用）。references/reader-skill-template.md—— 项目开发 skill 的 SKILL.md 模板（阶段二用）。references/feature-analysis.md—— 功能描述规范与功能分析流程（阶段三用）。
交付
- 完成后，报告：
1. 运行模式、文档保存路径、生成/补充的文件数与模块覆盖、工具与工具检查结论、范围边界与遗留项。
2. 生成的开发 skill 名称/位置及其编译/测试命令概览。
3. 功能分析结果：功能描述/下识别到的待办、已实现/测试/待用户确认的功能与版本。 - 若写了工作区临时草稿（.skill_build 等），交付后清理。
