基于文件系统的AI协作项目管理：构建持久化上下文与高效工作流

1. 项目概述：为什么我们需要一个“项目上下文管理器”？

如果你和我一样，经常使用像 OpenClaw 这类 AI 助手进行深度、长期的创作或开发工作，你肯定遇到过这个痛点：聊着聊着，项目就“丢了”。我说的“丢”，不是文件不见了，而是“上下文”断了。你可能在同一个主会话里同时推进着三四个项目——一个在写 Python 爬虫，一个在规划产品原型，还有一个在整理读书笔记。聊到一半，你切出去处理了个临时问题，或者干脆就是第二天重新打开助手，想继续昨晚的爬虫项目。这时，你发现你需要花好几分钟，甚至重新上传文件、复述一遍背景，才能让助手“回忆”起你昨天做到哪一步了。更糟的是，如果讨论过程中产生了一些关键决策、待办事项或者临时的代码片段，它们都散落在冗长的聊天记录里，像珍珠掉进了沙堆，下次想找出来复用，难上加难。

这就是project-context-manager这个 OpenClaw skill 要解决的核心问题：长期、多项目协作下的上下文管理与状态恢复。它不是一个花哨的 UI 或者一个试图读心术的黑盒，而是一套基于文件系统的、朴实但极其有效的“项目管理约定”和工作流。它的目标很简单：让你和 AI 助手之间的每一次长线协作，都像打开一个专业的 IDE 项目一样，拥有清晰的结构、可追溯的进度和随时可恢复的“断点”。它把一次性的、线性的聊天对话，升级成了一个可持久化、可分支、可归档的“项目工作空间”。

简单来说，这个 skill 为你和 AI 助手建立了一套共同遵守的“项目语言”。当你启动一个长期任务时，它会帮你初始化一个结构化的项目文件夹；当你需要暂停时，它会帮你把当前的讨论焦点、待办事项、关键结论固化到特定的 Markdown 文件中；当你想回来继续时，它能立刻带你回到上次的“断点”，无缝衔接。这尤其适合软件开发、内容创作、学术研究、复杂问题拆解等需要多轮深度交互的场景。如果你经常觉得和 AI 的对话“聊完就忘”、“难以承接”，那么这个工具很可能就是你工作流中缺失的那块拼图。

2. 核心设计思路：文件即上下文，约定优于配置

在深入使用细节之前，理解project-context-manager的设计哲学至关重要。这决定了你是否能用好它，以及它是否能真正融入你的工作流。它的核心思路可以概括为两点：“文件即上下文”和“约定优于配置”。

2.1 为什么是“文件”而不是“记忆”？

许多 AI 应用或插件试图在后台通过复杂的向量数据库或记忆机制来维护上下文。这听起来很智能，但也带来了不确定性：你永远不知道它“记住”了什么，又“忘记”了什么；它的记忆是黑盒，无法直接查看和编辑；一旦会话重置或切换，这些记忆就可能丢失。

project-context-manager反其道而行之，它认为最可靠、最透明、最可控的“记忆”载体，就是你本地硬盘上的文件。所有关键的上下文信息——项目目标、当前进度、待办事项、关键决策、甚至是用于恢复对话的“系统提示词”——都被要求以 Markdown 文件的形式，保存在一个结构清晰的项目目录里。这样做有几个巨大的优势：

1. 绝对可控与可移植性：文件在你手里。你可以用任何文本编辑器查看、修改、备份它们。你可以把整个项目文件夹压缩，发给同事，或者放到另一个设备上，上下文完整无损。
2. 人类与AI可共同读写：Markdown 是一种对人友好、对机器也易于解析的格式。你既可以自己编辑这些文件来更新进度，AI 助手也可以根据你们的对话，自动更新这些文件的内容。
3. 状态持久化，不依赖会话：只要文件在，项目的“状态”就在。无论你关闭 OpenClaw、重启电脑，还是过了一周再打开，只要加载这个项目目录，你就能立刻回到工作现场。
4. 便于版本管理：你可以用 Git 来管理整个项目文件夹。每一次重要的进度更新或决策记录，都可以是一次 commit。这为长期项目提供了天然的版本历史。

所以，这个 skill 本质上是一个“基于文件系统的上下文协议执行者”。它定义了一套文件应该怎么命名、放在哪里、包含什么内容，然后确保 AI 助手在项目模式下，严格地读取和更新这些文件。

2.2 “约定优于配置”的具体体现

为了让这套机制足够轻量、易用，skill 采用了“约定优于配置”的原则。这意味着，它提供了一套推荐的最佳实践和默认结构，你只需要遵循，就能获得绝大部分功能，无需进行繁琐的配置。

• 固定的核心文件：它建议每个项目都包含几个核心文件，如00_恢复入口.md、00_文档总索引与当前进度.md等。这些文件名和位置是约定好的，skill 会直接去寻找它们。
• 轻量级注册表：为了管理多个项目，它使用一个简单的 JSON 文件（如projects-registry.json）作为项目注册表。你不需要配置复杂的数据库，只需维护这个 JSON 文件，列出你的项目路径和名称。
• 明确的操作口令：进入、退出、恢复、固化项目，都通过几句自然语言口令触发（如“恢复项目”、“固化当前状态”）。这些口令是约定好的交互方式，简单直接。

这种设计极大地降低了使用门槛。你不需要理解背后复杂的逻辑，只需要记住几个简单的口令和文件结构，就能获得强大的项目管理能力。当然，这套约定也是可扩展的，你可以根据自己的习惯，在理解其原理后调整模板和流程。

3. 核心能力与工作流全解析

了解了设计思路，我们来看这个 skill 具体能做什么。它的所有功能都围绕一个核心工作流展开：项目的生命周期管理。我们可以把这个生命周期拆解为几个关键环节，每个环节都对应着 skill 的一项或多项核心能力。

3.1 项目初始化：从零搭建一个“可管理”的项目

当你开始一个全新的、预计会长期进行或需要多轮讨论的任务时，就应该为其“初始化”一个项目。这是整个工作流的起点。

典型场景：“我想开发一个个人财务跟踪的 CLI 工具，预计需要设计数据模型、编写核心逻辑、做数据可视化几个阶段，想和 AI 一步步讨论实现。”

你的操作：在 OpenClaw 中，你可以直接说：“帮我建一个长期项目，用来开发个人财务CLI工具。” 或者说：“给‘财务CLI工具开发’这个任务建立项目结构。”

Skill 的内部运作与你的实操：

1. 创建项目根目录：Skill 会首先询问你，希望把这个项目文件夹创建在什么位置（例如~/Documents/MyProjects/）。你需要提供一个路径。
2. 填充项目模板：接着，skill 会调用其自带的scripts/init_project.py脚本（或类似逻辑），将templates/目录下的所有模板文件，复制到你指定的新目录中。这包括：
   • 00_恢复入口.md: 这是最重要的文件，里面包含了用于让 AI 助手恢复项目上下文的核心提示词和指令。初始化时，它会包含项目名称、简要描述等占位符，等待后续填充。
   • 00_文档总索引与当前进度.md: 项目的“主页”，用于记录项目概述、最终目标、当前阶段、下一步待办（TODO）列表。
   • 01_项目会话与恢复机制说明.md: 给未来的你或协作者看的说明文档，解释这个文件夹的结构和如何恢复工作。
   • 99_关键决策记录.md: 用于记录在讨论过程中做出的所有重要设计决策、取舍原因。
   • checkpoints/和session-backups/目录：用于存放阶段性的快照和会话备份。
3. 更新项目注册表：skill 会自动（或提示你手动）将新项目的路径和名称，添加到本地的projects-registry.json文件中。这样，这个新项目就被纳入了统一管理。

实操心得：初始化时的关键一步初始化完成后，千万不要跳过“立即进入项目”这一步。你应该紧接着说“现在进入这个项目”或“恢复这个项目”。这样，skill 会引导 AI 助手读取刚创建的00_恢复入口.md，并根据里面的指令，将对话上下文切换到“项目协作模式”。助手会开始依据00_文档总索引与当前进度.md中的内容来理解项目背景，并等待你的进一步指令。如果你初始化完就直接开始聊别的，项目上下文并没有被真正“激活”。

3.2 项目进入与恢复：一键回到工作现场

这是 skill 最常用的功能。当你处理完其他事情，想继续之前某个项目时，就需要“恢复”或“进入”该项目。

典型场景：昨天你和助手讨论了财务CLI工具的数据模型设计，并约定今天实现核心计算逻辑。今天你打开 OpenClaw。

你的操作：直接说：“恢复项目。” 或 “进入项目。”

Skill 的内部运作与你的实操：

1. 读取注册表：Skill 会去查找预设位置（如工作空间根目录）的projects-registry.json文件。
2. 扫描与验证：它遍历注册表中列出的所有项目路径，检查每个路径是否存在，以及核心文件（如00_恢复入口.md）是否有效。
3. 列表展示：将所有有效的项目以列表形式呈现给你，通常包括项目名称和路径。
4. 用户选择：你需要从列表中选择你想要进入的那个项目（例如，“个人财务CLI工具”）。
5. 加载恢复入口：Skill 引导 AI 助手读取你选中项目下的00_恢复入口.md文件。这个文件里的指令会“告诉”助手：“现在你正在处理XXX项目，你的角色是XXX，当前进度是XXX，接下来应该关注XXX。” 同时，助手也会加载00_文档总索引与当前进度.md来了解最新情况。
6. 上下文切换完成：此时，AI 助手的“大脑”已经完全切换到了该项目的上下文中。它记得之前的设计决策（来自99_关键决策记录.md），清楚当前的待办事项，并准备好从上次的断点继续工作。你可以直接说：“我们昨天设计了数据模型，今天开始写计算收入的函数吧。” 助手能立刻理解。

注意事项：恢复的本质“恢复项目”并不是在“回忆”聊天历史，而是在根据文件重建一个高度结构化的、精准的上下文。因此，即使你清空了聊天记录，只要项目文件在，你依然可以完美恢复。这也意味着，你需要保持项目文件的更新，特别是00_文档总索引与当前进度.md里的 TODO 列表和当前阶段描述，这是恢复后助手行动的依据。

3.3 项目状态固化：保存关键决策与进度

在项目推进过程中，会不断产生新的进展、做出的决策、产生的代码片段。如果这些信息只停留在聊天记录里，它们就无法被下一次“恢复”有效利用。因此，需要定期“固化”项目状态。

典型场景：经过几轮讨论，你们确定了财务CLI工具使用 SQLite 作为本地数据库，并完成了数据库连接层的代码。

你的操作：在觉得达到一个阶段性节点时，对助手说：“固化当前项目状态。” 或 “更新恢复文件并保存当前断点。”

Skill 的内部运作与你的实操：

1. 总结当前进展：AI 助手会基于刚刚结束的对话轮次，提炼出关键信息：我们刚才做了什么？得出了什么结论？产生了什么有价值的产出（如代码块、文案）？
2. 更新核心文件：
   • 更新进度文件：将提炼出的“已完成事项”从00_文档总索引与当前进度.md的 TODO 列表中移到“已完成”部分，并可能细化或新增下一步的 TODO。
   • 记录关键决策：如果本次对话做出了重要选择（比如“选用 SQLite 而非 JSON 文件存储”），助手会将这个决策及其理由，整理成一段清晰的记录，追加到99_关键决策记录.md中。
   • 保存产出物：生成的代码、配置片段等，可能会被建议保存到项目目录下新建的对应文件中（如database.py），并在进度文件中加以说明。
3. （可选）创建检查点：在一些重大里程碑，你可以要求“创建一个检查点”。这可能会将整个项目目录打包备份到checkpoints/下，或者保存一份当前的完整会话记录到session-backups/。这提供了更粗粒度的时间旅行能力。

实操心得：固化时机的选择不要等到项目结束才固化。养成“讨论告一段落就固化”的习惯。例如，每完成一个功能模块的设计、每解决一个复杂的技术难题、每产生一份重要的文档草稿后，都执行一次固化操作。这能保证你的项目文件始终反映最新、最完整的进度，避免信息遗漏。你可以把“固化状态”当作是项目开发中的一次“保存”或“提交”。

3.4 项目退出：从项目模式回到普通聊天

当你需要暂时中断项目工作，去进行一些临时性的、不相关的查询或聊天时，就需要“退出”项目模式。

你的操作：直接说：“退出项目。” 或 “回到普通模式。”

Skill 的内部运作：这很简单。Skill 会引导 AI 助手清除当前的项目上下文（即不再主动引用项目文件夹内的那些特定文件），并将对话模式切换回普通的、无状态的问答模式。此时，助手不再“记得”项目里的 TODO 和决策，就像关闭了一个专属的工作空间，回到了公共大厅。

注意事项：退出前先固化一个非常好的实践是：在退出项目前，先执行一次“固化状态”。这样可以确保你在项目中的所有最新工作都已保存到文件。否则，退出后，刚才最后一段对话中的宝贵内容可能就只留在了易失的聊天记录里。

3.5 接管已有项目目录：将旧项目纳入管理

你很可能已经有一些正在进行中的、文件夹里堆满了资料的项目。project-context-manager允许你将这些现有目录“接管”过来，为其补全管理所需的结构，从而享受同样的上下文管理能力。

你的操作：上传或指向一个已有目录，然后对助手说：“这是我的项目目录‘旧营销方案分析’，帮我接管。” 或 “把这个目录纳入项目管理。”

Skill 的内部运作与你的实操：

1. 检查目录：Skill 会检查该目录下是否已存在部分核心文件（比如你自己建的README.md或notes.txt）。
2. 补充缺失结构：它会将缺失的模板文件（如00_恢复入口.md、99_关键决策记录.md等）复制到该目录中，但会避免覆盖已有的文件。
3. 引导初始化：接着，它会引导你一起，基于现有目录的内容，来初始化00_恢复入口.md和00_文档总索引与当前进度.md。例如，它可能会问你：“这个项目的核心目标是什么？”、“根据现有文件，我们当前进展到哪一步了？”，然后将你的回答整理进模板。
4. 注册项目：最后，将这个已有目录的路径添加到项目注册表中。

这个过程相当于为你混乱的旧项目文件夹“赋能”，给它装上了一个标准化的“仪表盘”和“导航系统”。

4. 项目结构与文件详解：每一个文件的作用

要真正驾驭这个 skill，你需要理解它推荐的项目结构中，每一个文件和目录存在的意义。这能帮助你在必要时手动调整或排查问题。

你的项目文件夹/ ├── 00_恢复入口.md # 【核心】项目上下文的“总开关” ├── 00_文档总索引与当前进度.md # 【核心】项目的“实时仪表盘” ├── 01_项目会话与恢复机制说明.md # 给人类看的说明书 ├── 99_关键决策记录.md # 项目的“设计决策日志” ├── checkpoints/ # 重大版本快照（可选） ├── session-backups/ # 原始会话备份（可选） └── （你的其他项目文件...） # 代码、文档、数据等

4.100_恢复入口.md：项目的灵魂文件

这是最重要的文件，没有之一。它的内容是一段精心编写的、给 AI 助手看的“系统提示词”。当你执行“恢复项目”时，助手读到的就是它。

一个简化示例：

# 项目恢复入口：个人财务CLI工具 ## 项目状态：激活 **当前模式**：项目协作模式。请严格遵循以下指令。 ## 你的角色 你是专注于Python后端开发的专家助手，正在与用户协作开发一个命令行个人财务跟踪工具。 ## 核心上下文来源 1. 首要参考：`00_文档总索引与当前进度.md` 中的项目概述、目标和 **【当前进度】**。 2. 决策依据：`99_关键决策记录.md` 中记录的所有历史决策。 3. 本项目目录下的所有文件（`.py`, `.md`, `.sql`等）均为可用资源。 ## 当前阶段与行动指南 - **阶段**：核心功能开发阶段。 - **上一轮进展**：已完成数据库连接层 (`database.py`) 和收入/支出数据模型定义。 - **本轮焦点**：根据 `00_文档总索引与当前进度.md` 中【下一步TODO】列表的第一项开始工作。 - **工作方式**：每次回复应紧扣项目目标，优先推进TODO项。所有代码修改应指向本项目目录下的具体文件。重要讨论结论需建议用户“固化状态”。 ## 固化与退出 - 当用户说“固化状态”时，协助更新 `00_文档总索引与当前进度.md` 和 `99_关键决策记录.md`。 - 当用户说“退出项目”时，结束本段提示词的约束，回到普通对话模式。

它的作用：

• 身份设定：告诉助手在这个项目里应该扮演什么角色（财务专家、代码助手、写作教练等）。
• 上下文锚定：明确指出核心信息来自哪几个文件，防止助手“瞎猜”或使用过时的记忆。
• 行动规范：规定助手应该如何工作（例如，紧盯TODO列表，建议固化状态）。
• 指令绑定：将“固化”、“退出”等自然语言口令与具体的文件操作关联起来。

注意事项：维护恢复入口随着项目演进，你的目标或助手的角色可能需要微调。你可以手动编辑这个文件。例如，从“开发”阶段进入“测试”阶段后，你可以把“你的角色”部分从“开发专家”改为“测试与调试专家”，并更新“行动指南”。这能让恢复后的助手行为更贴合当前需求。

4.200_文档总索引与当前进度.md：项目的实时仪表盘

这个文件是项目的“活页手册”，由你和助手共同维护，始终保持最新。

典型结构：

# 项目：个人财务CLI工具 **创建日期**：2023-10-27 **最后更新**：2023-10-28 [由助手更新] ## 1. 项目概述 开发一个本地命令行工具，用于跟踪个人每日收入、支出，生成月度报表，并进行简单的消费分类分析。 ## 2. 终极目标 - V1.0：实现基础的增删改查(CRUD)和月度总结。 - V2.0：增加消费类别自动归类、可视化图表导出。 ## 3. 当前进度 (【重点阅读区域】) **当前阶段**：核心功能开发阶段 (第二阶段) **最近进展**： - [x] 项目初始化与需求确认 (2023-10-27) - [x] 技术选型与架构设计：确定使用Python + SQLite + Click库 (2023-10-27) - [x] 数据库连接层与核心数据模型 (`models.py`) 实现 (2023-10-28) - [ ] **【进行中】** 收入/支出记录的核心业务逻辑层 (`service.py`) ## 4. 下一步 TODO (【行动依据】) 1. [高优先级] 实现 `service.py` 中的 `add_transaction(amount, category, date, note)` 函数。 2. [高优先级] 实现 `get_monthly_summary(year, month)` 函数。 3. [中优先级] 设计并实现主命令行界面 (`cli.py`) 的骨架。 4. [低优先级] 编写初步的单元测试。 ## 5. 项目文件索引 - `database.py`: SQLite数据库连接与初始化。 - `models.py`: 数据表模型定义（Transaction表）。 - `service.py`: (待实现) 核心业务逻辑。 - `cli.py`: (待实现) 命令行交互入口。 - `requirements.txt`: 项目依赖。 ## 6. 待澄清问题 - 消费分类是预定义固定列表，还是允许用户自定义？

它的作用：

• 进度跟踪：清晰的“已完成/进行中”列表，让你和助手一眼就知道项目在哪。
• 任务驱动：“下一步TODO”列表是恢复项目后，助手立即开始工作的行动清单。你们可以一起从上到下攻克。
• 信息聚合：项目概述、文件索引、待澄清问题都集中在这里，是项目的总百科。

实操心得：如何写好TODO把TODO写得具体、可执行。避免“完善功能”这种模糊描述，而是写成“实现XX函数的YY异常处理”。这样，当助手恢复上下文后，它能立刻理解要做什么，并给出更精准的帮助。

4.399_关键决策记录.md：项目的设计日志

这个文件记录所有“我们为什么这么做”的决策，对于长期项目和团队协作尤其宝贵。

示例记录：

## 决策记录 ### 2023-10-27: 数据存储方案选择 **问题**：个人财务数据是存储在本地JSON文件还是SQLite数据库中？ **选项**： 1. JSON文件：简单，无需额外依赖，但并发读写差，查询能力弱。 2. SQLite：轻量级数据库，支持SQL查询，事务安全，是Python标准库一部分。 **决策**：选择SQLite。 **理由**： 1. 数据关系简单但未来可能变复杂（如多账户、标签），SQLite更易扩展。 2. 需要经常进行按月汇总、按类别筛选等查询，SQL查询比手动解析JSON更高效可靠。 3. `sqlite3`模块是Python内置，不增加额外依赖，符合工具“开箱即用”的定位。 **记录人**：与助手讨论后共同决定。

它的作用：

• 避免重复争论：当几周后你忘了为什么选SQLite时，翻看这里就能立刻明白。
• 保持一致性：确保项目不同阶段的设计遵循同一套原则。
• 知识传承：如果你是项目负责人，这份记录能帮助新加入的协作者（或未来的你）快速理解项目脉络。

4.4 其他文件与目录

• 01_项目会话与恢复机制说明.md：这是一份静态文档，用于向你自己或他人解释这个文件夹为什么长这样，以及如何使用这套机制。在项目初始化后通常不需要频繁改动。
• checkpoints/：建议在这里存放项目重大里程碑的压缩包或快照。例如，在完成V1.0所有核心功能后，可以将整个项目目录（除checkpoints本身外）打包成v1.0-core-functions.zip存于此。这提供了额外的保险。
• session-backups/：你可以选择将一些重要的原始对话记录导出为文本文件存于此。虽然结构化文件是主要上下文，但原始对话有时包含有用的思维过程。

5. 项目注册表与多项目管理

当你拥有多个项目时，一个统一的“入口”就变得必要。project-context-manager通过一个轻量级的项目注册表（Project Registry）来实现这一点。

5.1 注册表是什么？

它通常是一个位于你工作空间根目录下的 JSON 文件，例如：<你的工作区>/projects-registry.json。

内容示例：

{ "projects": [ { "name": "个人财务CLI工具", "path": "/Users/liuboyang/Documents/Projects/finance-cli", "description": "开发用于跟踪个人收支的命令行工具", "lastAccessed": "2023-10-28" }, { "name": "AI写作助手Prompt优化研究", "path": "/Users/liuboyang/Documents/Research/prompt-optimization", "description": "系统化测试和优化用于内容创作的AI提示词", "lastAccessed": "2023-10-25" }, { "name": "家庭网络升级方案", "path": "/Users/liuboyang/Documents/Plans/home-network", "description": "规划Mesh组网、NAS选型及智能家居网络隔离", "lastAccessed": "2023-10-20" } ] }

5.2 Skill 如何与注册表交互？

1. 列表展示：当你说“恢复项目”时，skill 会读取这个 JSON 文件，将projects数组里的每一项（项目名和描述）呈现给你选择。
2. 路径验证：在你选择后，skill 会检查path字段指向的目录是否存在，以及核心文件是否完好。如果路径失效，它会提示你该项目可能已被移动或删除。
3. 自动更新：当你通过 skill “初始化新项目”或“接管已有目录”时，skill 通常会自动向这个注册表文件添加新条目。同样，当你“退出项目”时，它可能会更新该项目的lastAccessed时间戳。

5.3 如何手动维护注册表？

虽然 skill 会尝试自动维护，但了解手动维护很有必要，尤其是在项目文件夹被移动，或者你想清理旧项目时。

• 添加项目：直接用文本编辑器打开projects-registry.json，按照格式添加一个新的对象到projects数组中即可。确保path是绝对路径或相对于注册表文件的正确相对路径。
• 移除项目：直接从projects数组中删除对应的对象条目。注意：这只是从注册表列表中移除，并不会删除你的项目文件夹本身。
• 修改项目：你可以修改name、description或更新path（如果项目搬家了）。

注意事项：注册表的路径确保projects-registry.json文件放在一个固定的、不会被轻易移动或删除的位置，并且这个位置被 OpenClaw 或你的助手环境所知晓（通常需要在 skill 配置或环境变量中设置）。如果注册表文件本身丢了，skill 就无法列出你的项目了。

6. 常见问题与排查技巧实录

在实际使用中，你可能会遇到一些小问题。以下是我在长期使用中积累的一些常见情况和解决方法。

6.1 问题：执行“恢复项目”后，助手好像没进入状态，还在聊普通话题。

• 可能原因1：项目注册表路径错误或文件丢失。
  • 排查：检查 OpenClaw 或 skill 的设置，确认projects-registry.json的预期路径是否正确。直接去那个路径下看看文件是否存在。
  • 解决：如果文件丢失，尝试从备份恢复，或手动重建一个。如果路径错误，修正配置。
• 可能原因2：项目目录下的00_恢复入口.md文件内容为空或格式严重错误。
  • 排查：打开你选择的那个项目文件夹，检查00_恢复入口.md。它应该包含有效的 Markdown 和给助手的明确指令。
  • 解决：可以手动编辑该文件，或者更简单的方法：退出当前会话，然后重新对该项目目录执行一次“接管已有项目目录”操作。skill 会尝试修复或重新初始化核心文件（注意备份原有文件）。
• 可能原因3：AI 助手的上下文长度有限，而00_恢复入口.md加上00_文档总索引与当前进度.md的内容太长，导致核心指令被截断。
  • 排查：检查这两个文件的大小。如果它们加起来超过了几千字（取决于模型），就可能出问题。
  • 解决：精简文件内容。00_恢复入口.md只保留最核心的角色和指令。00_文档总索引与当前进度.md中的历史记录可以适当归档，只保留最近的关键进展和当前TODO。

6.2 问题：我想让助手关注项目里的一个特定文件，但它好像没看到。

• 可能原因：00_恢复入口.md中“核心上下文来源”部分可能没有明确指示助手去读取项目目录下的所有文件，或者助手的能力限制导致它无法主动遍历目录。
  • 解决：最可靠的方法是在对话中直接提及并引用该文件。例如：“请查看我们项目目录下的design-sketches.md文件中的第三点方案，然后基于它进行讨论。” 或者，你可以把该文件的关键内容复制到当前的对话中。同时，你可以修改00_恢复入口.md，在“核心上下文来源”里加上一句：“本项目目录下的所有相关文件均可作为参考依据。”

6.3 问题：“固化状态”时，助手更新的内容不符合我的预期。

• 可能原因1：对话历史中的信息不够明确，导致助手总结提炼时出现偏差。
  • 解决：在触发“固化状态”前，可以先用一两句话帮助手梳理一下：“我们来总结一下刚才的进展：我们确定了使用Pandas来处理数据，并且你提供了数据清洗函数的初步代码，对吗？” 得到助手确认后，再执行固化。这相当于给助手一个明确的总结方向。
• 可能原因2：00_文档总索引与当前进度.md中的 TODO 列表格式不标准，助手难以解析。
  • 解决：保持 TODO 列表的格式简洁一致。使用- [ ]表示未完成，- [x]表示已完成。每个 TODO 项尽量是一句清晰的陈述句。这能提高助手自动更新的准确性。
• 可能原因3：这是AI的固有局限性，它可能无法完美理解所有对话的细微之处。
  • 解决：将“固化状态”视为一个半自动的过程。助手更新文件后，你一定要亲自检查一下00_文档总索引与当前进度.md和99_关键决策记录.md的更新结果。如果有不准确或遗漏的地方，手动修改一下。这是人机协作中必要的质量把关环节。

6.4 问题：项目文件越来越多，感觉有点乱。

• 解决：这是正常现象。建议建立子目录进行分类管理。例如：

  项目文件夹/ ├── docs/ # 存放设计文档、需求说明等 ├── src/ # 存放源代码 ├── data/ # 存放测试数据或生成的数据 ├── notes/ # 存放临时性的讨论笔记或参考资料 └── （核心管理文件依然在根目录）

  只要核心的00_*.md文件在根目录，skill 就能正常工作。你的其他文件可以按任何逻辑组织。

6.5 高级技巧：定制你自己的项目模板

如果你发现默认的模板文件不完全符合你的工作习惯，完全可以进行定制。

1. 找到 skill 安装目录下的templates/文件夹。
2. 复制里面的模板文件到你自己的一个“自定义模板”目录。
3. 按照你的喜好修改这些模板文件的内容。例如，你可以在00_恢复入口.md中定义更详细的角色指令，或者在00_文档总索引与当前进度.md中增加“风险与障碍”章节。
4. 下次初始化新项目时，不要使用 skill 的默认命令。你可以手动创建项目文件夹，然后把你自定义的模板文件复制进去，再手动编辑00_恢复入口.md中的项目名称和描述，最后手动将该目录添加到projects-registry.json中。

这套系统的强大之处就在于它的灵活性和基于文件的透明性。你越了解它，就越能把它改造得适合自己的工作流。