القائمة
维护 pi-go 项目文档结构与一致性。当用户提到'维护一下文档'、'更新文档'、'文档整理一下'、'docs 该整理了'、'同步文档和代码'、'整理 docs 目录'等意图时加载此 skill。
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
استنادا إلى تصنيف SOC المهني
| name | docs-maintainer |
| description | 维护 pi-go 项目文档结构与一致性。当用户提到'维护一下文档'、'更新文档'、'文档整理一下'、'docs 该整理了'、'同步文档和代码'、'整理 docs 目录'等意图时加载此 skill。 |
绝对路径：/Users/weijian/Desktop/develop/test/pi/pi-go
所有路径基于此根目录，下文简称 {pi-go}。
本 skill 维护以下目录结构，迁移时必须遵守：
docs/
├── README.md # 文档总索引
├── PROJECT_CONTEXT.md # 项目上下文快照
├── PRODUCT_ROADMAP.md # 产品路线图（长期）
├── CONTRIBUTING.md # 贡献指南（长期）
├── deploy.md # 部署说明（长期）
│
├── references/ # 稳定查阅资料（接口/集成/项目快照）
│
├── decisions/ # 当前采纳判断（会演进，但比 research 更接近团队共识）
│
├── research/ # 外部项目调研原始报告（天然会过期）
│
├── dev/ # 开发文档（4-agent 流水线产出）
│ └── {topic}/ # 一个主题一个目录
│ ├── proposal.md # 计划 agent 产出
│ ├── review.md # 审核 agent 产出
│ └── execution-plan.md # 确认后的执行文档
│
└── archive/ # 已完成的开发主题
└── {topic}/ # 整个目录从 dev/ 移入
每个 dev/ 下的文档必须有 YAML 头：
---
status: draft | reviewed | approved | done
author: plan-agent | review-agent | exec-agent | research-agent
created: YYYY-MM-DD
updated: YYYY-MM-DD
reviewer: review-agent # review.md 专有
review-status: pending | approved | rejected | needs-revision # review.md 专有
depends-on: [] # 可选
---
状态流转：draft → reviewed → approved → done（rejected/needs-revision 回到 draft）
| 性质 | 归属 | 示例 |
|---|---|---|
| 长期有效的项目级文档 | docs/ 根目录 | PROJECT_CONTEXT、ROADMAP、CONTRIBUTING |
| 稳定查阅资料 | docs/references/ | 第三方集成参考、项目快照、接口说明 |
| 基于调研得出的当前采纳判断 | docs/decisions/ | skills vs application、goal/compact 取舍 |
| 外部项目调研原始分析 | docs/research/ | 竞品分析、框架对比、源码调查 |
| 4-agent 流水线产出的开发文档 | docs/dev/{topic}/ | 提案、审核、执行计划 |
| 已完成的开发主题 | docs/archive/{topic}/ | 已归档的执行计划 |
当用户说"文档有没有过时"、"快速检查一下文档"时，可以跳过完整的 4 阶段流程，只做以下快速检查：
find docs/ -name "*.md" | sort vs docs/README.md 中列出的文件dev/ 下每个主题的最新 updated 日期 + status，标记满足归档条件的输出一个简洁的清单即可，不做修改。
find {pi-go}/internal -type f -name "*.go" | head -80
grep -r "^type.*interface {" {pi-go}/internal --include="*.go" -l
grep -r "^func New" {pi-go}/internal --include="*.go" | head -30
不要写死文件列表，用 find 动态发现：
find {pi-go}/docs -name "*.md" -type f | sort
同时扫描根目录 README：
head -50 {pi-go}/README.md
对每个文件：
dev/ 下的文档：检查元信息头是否完整、状态是否合理docs/README.md：检查索引是否覆盖所有文件docs/PROJECT_CONTEXT.md：检查与源码一致性{pi-go}/README.md：检查与源码一致性（见下方专项检查）archive/ 下的文件：只读头部，判断归档是否合理对每份文档做以下检查：
| 检查项 | 判断标准 |
|---|---|
| 索引缺失 | docs/README.md 没有列出存在的文件 |
| 索引多余 | docs/README.md 列出了但文件已不存在 |
| 内容过时 | 文档描述与当前源码不一致 |
| 归档判断 | dev/ 下满足归档条件的主题（见下方归档判断规则） |
| 元信息头 | dev/ 下的文档缺少 YAML 头或字段不完整 |
| 归属错误 | 文档放在错误的目录（如参考资料放在根目录） |
| 决策/调研混放 | 带明确采纳建议与路线图的文档放在 research/ 或 references/ |
| PROJECT_CONTEXT | 架构、能力表、文件索引与实际代码不匹配 |
| 根 README 过时 | README.md 中的 API 路由、工具/命令列表、环境变量、代码统计与实际代码不一致 |
| 已完成未归档 | dev/ 下描述的改动已出现在 main 分支代码中，但目录仍在 dev/ |
满足以下任一条件，即可建议归档：
doneinternal/ 对应文件中（通过 git log + grep 交叉验证）updated 日期距今超过 30 天，且 execution-plan.md 的 status 为 approved 或 done注意：
deferred状态的主题留在dev/，不归档。
dev/ 主题的状态列internal/ 目录结构变化时更新根目录 README.md 是项目的门面，需要与代码保持同步。检查以下内容：
internal/server/server.go 中注册的路由对比internal/agents/coding/commands/builtins.go 中注册的命令对比internal/tools/ 下的工具文件对比internal/config/config.go 中的环境变量对比internal/ 下的包结构对比，新增能力需补充go.mod 中的版本一致满足以下条件时，将 dev/{topic}/ 整个目录移入 archive/：
status 均为 donemv {pi-go}/docs/dev/{topic} {pi-go}/docs/archive/{topic}
不要归档：PROJECT_CONTEXT、ROADMAP、CONTRIBUTING、deploy.md
文档放错目录时，移到正确位置：
references/decisions/research/dev/{topic}/dev/ 下缺少 YAML 头的文档，根据内容推断并补全。
## 文档维护报告 {YYYY-MM-DD}
### 已修正
- [更新] docs/README.md：补充了 X 的索引
- [归档] dev/zzz/ → archive/zzz/
- [更新] PROJECT_CONTEXT.md：核心能力表新增 W
- [更新] README.md：API 路由表新增 /models 等端点
- [归属] feishu-ref.md → references/
### 无需修正
- CONTRIBUTING.md：内容准确
- deploy.md：内容准确
### 需人工确认
- XXX.md：描述了尚未确定的设计方向，建议确认后更新