Zions-store/project-ledger

版权所有 (C) 2026 ZionXiaoxiSuOGLocGo SPDX-License-Identifier: GPL-3.0-or-later

project-docs

创建并维护一个三文档项目知识体系。支持由 project-onboard 检测到的所有项目类型——根据项目类型自动选择正确的模板。

三文档系统

文件	用途	更新频率
AGENTS.md	项目概览：身份、目录结构、类架构、入口点、依赖、备注	每完成一个里程碑（约 3-5 个新文件/类）
PROJECT_STATE.md	活文档：完整的类/源码谱系（含参数）、配置、模块图、系统流程、完成/待办列表	每次会话结束时
DEVLOG.md	开发日志：时间线条目——做了什么、为什么做、学到了什么	每天或每个功能里程碑

有关更新触发规则、内容边界和一致性检查的详细规则，请参见 maintenance-spec.md。

模板选择

模板遵循与 project-onboard 规则包相同的自动发现模式。该技能会尝试加载 templates/<type>/PROJECT_STATE.md.tmpl，其中 <type> 是 AGENTS.md 基本信息中的 Type 值（小写）。如果没有类型特定的模板，则回退到 templates/PROJECT_STATE.md.tmpl。

templates/<type>/PROJECT_STATE.md.tmpl 存在？→ 使用它
                                    不存在 → 使用 templates/PROJECT_STATE.md.tmpl（通用回退）

为新的引擎或框架添加支持：创建 templates/<type>/PROJECT_STATE.md.tmpl。无需修改代码——技能会自动发现它。

所有类型共享 templates/DEVLOG.md.tmpl（与项目类型无关）。

AGENTS.md → PROJECT_STATE.md 字段映射

从 AGENTS.md 数据预填充 PROJECT_STATE.md 时，使用以下映射：

AGENTS.md 章节	AGENTS.md 字段	STATE 模板章节	STATE 占位符
基本信息	类型、语言、框架/引擎、关键依赖	§1 项目标识	{{PROJECT_TYPE}}, {{LANGUAGE}}, {{FRAMEWORK}}, {{KEY_DEPENDENCIES}}
基本信息	引擎（针对游戏项目）	§1 项目标识	{{ENGINE_VERSION}}
目录结构	目录及其描述	§2 目录结构	{{DIRECTORY_TREE}}（通用）或 Source/{{MODULE_NAME}}/...（UE）
核心架构	关键文件/类及其角色	§3 源码/脚本谱系	{{CLASS_NAME}}, {{RESPONSIBILITY}}, {{FILE_NAME}}
依赖	包摘要	§4 配置 / §7 依赖	{{CONFIG_KEY}}, {{DEP_NAME}}（根据上下文）
构建与运行	构建/测试命令	§9 构建与运行	{{BUILD_CMD}}, {{RUN_CMD}}, {{TEST_CMD}}
入口点	启动文件/场景及其角色	§1 项目标识（模块）	{{MODULE_NAME}}

对于非英语输出：翻译章节标题、标签和占位符描述，但保留 {{占位符}} 标记不变。

何时使用此技能

• 用户说“初始化项目文档” / “init project docs” / “建立文档体系” / “project-docs”
• 新项目需要创建 PROJECT_STATE.md 和 DEVLOG.md
• 现有项目已有 AGENTS.md 但缺少其他两个文档
• 用户在会话结束后要求更新项目状态

工作流程

1. 初始化（新项目 / 缺少文档）

0. 询问用户文档使用哪种语言。如果用户跳过或说“无所谓”，则默认为英语。LLM 能输出的任何语言都支持——代理在生成时处理翻译：

   “项目文档应使用哪种语言书写？默认：英语。LLM 能输出的任何语言都支持。”

1. 检查 AGENTS.md 是否存在。

   • 如果不存在：提议先运行 project-onboard 技能生成 AGENTS.md。在此处停止。
   • 如果存在：读取 AGENTS.md 并提取：
     • 项目名称
     • 类型（来自基本信息——例如 "unreal", "unity", "nodejs", "python"）
     • 核心架构（类、文件、角色）

2. 检测模板：根据提取的类型（小写），尝试加载类型特定的模板。如果没有匹配，则回退到通用模板：

   • 首先尝试 templates/<type>/PROJECT_STATE.md.tmpl
   • 如果该文件不存在，则使用 templates/PROJECT_STATE.md.tmpl（通用）

3. 从所选模板生成 PROJECT_STATE.md：

   • 根据上述字段映射表，从 AGENTS.md 数据预填充 §1-§3。
   • 其余章节保留占位符结构，以便将来更新。

4. 从 templates/DEVLOG.md.tmpl 生成 DEVLOG.md：

   • 填写项目名称。
   • 保留条目模板，准备用于第一条开发日志条目。

5. 在 AGENTS.md 顶部、# 项目名称 标题行之后（但在其余内容之前）添加以下块：

   ## 请先阅读
   
   1. 阅读 `PROJECT_STATE.md`——当前任务状态和待办事项（§10）
   2. 阅读 `DEVLOG.md`——最近的开发历史
   
   ---
   

6. 报告已创建的内容、使用的模板以及文档的语言。

2. 更新（已有文档）

1. 读取 PROJECT_STATE.md → 识别 §10 待办列表
2. 询问用户完成了什么 / 发生了什么变化
3. 更新受影响的章节：
   • §1-§2：如果项目标识或目录结构发生变化
   • §3：新增的类、文件或关键成员
   • §4：配置变更（蓝图属性、预制体设置或通用配置）
   • §5：输入绑定、操作映射或模块/包变更
   • §6：系统逻辑、架构流程或游戏系统变更
   • §7：场景/关卡配置或外部服务变更
   • §8：任何数值参数变更
   • §9：构建问题、新编译错误或命令变更
   • §10：始终更新——完成列表、待办列表、已知问题
4. 向 DEVLOG.md 追加条目（按照 maintenance-spec.md 的格式）
5. 如果架构发生变化（新增类、插件、目录）→ 更新 AGENTS.md

3. 一致性检查

每次更新后，验证：

• AGENTS.md 和 PROJECT_STATE.md 之间没有重叠数据（架构概览 vs 参数细节）
• AGENTS.md 中的目录结构条目在 PROJECT_STATE.md 中都有对应
• PROJECT_STATE.md §8 参数值与实际源码默认值一致（例如 .h 默认值、配置文件值、BP CDO 覆盖值）
• PROJECT_STATE.md §10 待办列表不与 DEVLOG.md 最新条目矛盾（如果 DEVLOG 说已完成，STATE 应匹配）
• 三份文档之间没有重复信息（一个事实 = 一个位置）

模板

模板按项目类型自动发现——没有硬编码的映射表。目录结构镜像了 project-onboard 的参考结构：

templates/
├── DEVLOG.md.tmpl              ← 所有类型（通用）
├── PROJECT_STATE.md.tmpl       ← 回退（通用）
├── unreal/PROJECT_STATE.md.tmpl     ← Unreal Engine
└── unity/PROJECT_STATE.md.tmpl      ← Unity

templates/<type>/PROJECT_STATE.md.tmpl 文件是可选的。技能会尝试加载与 AGENTS.md 的类型匹配的模板；如果不存在，则使用根目录下的通用模板。

添加新类型：创建 templates/<type>/PROJECT_STATE.md.tmpl，包含针对该类型的章节。技能会在下次运行时自动发现——无需修改代码。

规则

• 永不覆写 现有文件。如果文档已存在，则就地更新。
• 尊重内容边界：AGENTS.md = 架构概览。PROJECT_STATE.md = 参数细节 + 状态。DEVLOG.md = 时间线叙述。
• 维护规范：参见 maintenance-spec.md 了解确切的更新触发条件、内容边界和禁止的做法。
• 项目特定的路径/类名 在 STATE/DEVLOG 中是预期的——这些是项目文档，不是可复用的手册。