别再手动整理需求了！这个开源项目让文件成为AI规划的最佳拍档
为什么这个项目值得关注
在日常开发中，你是否遇到过这些痛点？
团队成员通过各种渠道（邮件、聊天工具、文档）提交需求，结果需求散落各处，整理起来费时费力。每次做项目规划都要反复确认：“这个需求到底是谁提的？”“优先级是什么？”“ deadline 是哪天？”
OthmanAdi/planning-with-files 正是为解决这些问题而生的开源工具。它创新性地将文件作为 AI 规划系统的核心交互载体，让你可以用最自然的方式管理需求、追踪进度、协调团队。
这个项目的核心理念非常独特：与其让 AI 直接对话，不如让 AI 读取文件、执行文件、再输出文件。每一份文档都是信息的载体，每一次规划都是文件的流转。这种设计带来了几个显著优势：
信息完整性：所有需求、进度、决策都以文件形式保存，可以追溯历史版本，不会因为对话结束而丢失关键信息。协作便利性：团队成员可以通过共享文件来传递需求，无需担心消息刷屏导致的关键信息被淹没。AI 友好性：文件结构清晰、格式统一，AI 更容易理解和处理，减少了歧义和误解。
更重要的是，这个项目完全开源，你可以根据自己团队的实际情况进行定制和扩展。无论是小型创业团队还是大型企业，都可以从中受益。
环境搭建：从零开始配置开发环境
在开始使用这个项目之前，我们需要配置好开发环境。整个过程分为以下几个步骤，我会详细讲解每一步的操作。
系统要求确认
首先确认你的系统满足以下要求：
操作系统方面，项目支持主流的 Linux、macOS 和 Windows 系统。如果你使用 Windows，建议通过 WSL2（Windows Subsystem for Linux）来获得更好的体验。
Python 版本需要 3.8 或更高版本。你可以使用以下命令检查当前 Python 版本：
python --version
如果版本低于 3.8，建议使用 pyenv 或 conda 来管理多个 Python 版本。
安装项目依赖
克隆项目仓库到本地：
git clone https://github.com/OthmanAdi/planning-with-files.git
cd planning-with-files
查看项目的依赖文件，通常是 requirements.txt 或 pyproject.toml。安装依赖前，建议创建一个虚拟环境来隔离项目依赖：
python -m venv venv
source venv/bin/activate # Linux/macOS
# venv\Scripts\activate # Windows
然后安装项目依赖：
pip install -r requirements.txt
如果项目使用 Poetry 进行包管理，可以运行：
poetry install
配置 API 密钥
大多数 AI 规划工具需要调用外部 API，因此需要配置相应的密钥。项目通常支持多种 AI 提供商，包括 OpenAI、Anthropic 等。
创建一个配置文件，通常命名为 .env 或 config.yaml：
# .env 文件示例
OPENAI_API_KEY=sk-your-api-key-here
ANTHROPIC_API_KEY=sk-ant-your-api-key-here
DEFAULT_MODEL=gpt-4
LOG_LEVEL=INFO
从 AI 提供商官网获取 API 密钥后，将其填入配置文件中。注意保护好密钥，不要将其提交到版本控制系统。
验证安装
安装完成后，运行项目提供的测试脚本来验证配置是否正确：
python -m planning_files verify
如果看到类似下面的输出，说明环境配置成功：
=== 配置验证结果 ===
Python 版本: 3.10.12 ✓
依赖包完整性检查 ✓
API 密钥配置 ✓
配置文件有效性 ✓
所有检查通过，可以开始使用！
核心功能详解
文件驱动的任务管理
项目最核心的设计理念是“文件即任务”。每一个任务、需求、决策都被表示为一个或多个文件。这种设计带来了几个关键优势：
版本可控：借助 Git 等版本控制系统，你可以轻松回溯任何一个任务的历史变更。每次规划调整都有完整的审计轨迹。
易于协作：团队成员可以通过标准的文件操作（创建、编辑、分享）来参与规划，无需学习特定工具。
AI 可读：文件的结构化特性使 AI 能够准确理解任务上下文，减少了模糊指令导致的执行偏差。
具体来说，项目的文件系统结构通常如下：
project_root/
├── plans/ # 存放所有规划文档
│ ├── 2024/
│ │ ├── Q1/ # 按时间组织
│ │ └── Q2/
│ └── archive/ # 历史归档
├── tasks/ # 任务文件
│ ├── active/ # 进行中的任务
│ └── completed/ # 已完成的任务
├── requirements/ # 需求文档
│ ├── incoming/ # 新收到的需求
│ ├── reviewed/ # 已审核的需求
│ └── approved/ # 已批准的需求
└── configs/ # 配置文件
├── priorities.yaml # 优先级定义
└── workflows.yaml # 工作流配置
智能需求解析
项目内置了强大的需求解析引擎。当你将一段自然语言描述写入文件后，AI 会自动识别并提取关键信息：
任务名称是什么？负责人是谁？截止日期是哪天？优先级是高是低？有哪些依赖关系？
解析后的信息会被结构化存储，便于后续的排序、筛选和执行。
例如，当你创建这样一个需求文件：
# requirements/incoming/用户反馈-登录问题.txt
## 原始需求描述
用户反馈在移动端访问时，偶尔会出现登录失败的情况。
具体表现为：输入正确的用户名和密码后，页面提示“登录超时”，但重新尝试后又可以正常登录。
这个问题影响了约 15% 的移动端用户。
## 来源信息
提交人：张三
提交时间：2024-01-15
来源渠道：客服工单 #2024-0892
## 预期目标
解决这个问题后，移动端登录成功率应该达到 99% 以上。
AI 会自动解析出：
{
"task_name": "修复移动端登录偶发失败问题",
"description": "用户反馈在移动端访问时，偶尔会出现登录失败的情况...",
"submitter": "张三",
"submit_time": "2024-01-15",
"source": "客服工单 #2024-0892",
"priority": "high", # AI 根据影响范围判断
"deadline": None, # 未明确指定
"dependencies": [],
"tags": ["mobile", "login", "bug"]
}
自动优先级排序
项目会根据多个维度自动计算和调整任务优先级：
业务价值维度：任务完成后能带来多少业务收益？用户反馈强烈程度如何？
紧急程度维度：是否存在硬性截止日期？问题是否正在影响生产环境？
依赖关系维度：哪些任务是其他任务的前置条件？
资源需求维度：任务需要多少开发时间？需要哪些特定技能？
综合这些维度，AI 会给出一个平衡后的优先级建议。但最终的优先级决策仍然由人类做出，AI 只是提供参考建议。
进度追踪与报告生成
项目提供了完善的进度追踪功能。你可以为每个任务设置状态（待处理、进行中、阻塞、已完成），系统会自动收集进度信息。
每周或每月，系统可以自动生成进度报告：
# reports/weekly/2024-W03.md
## 本周进度报告（2024-01-15 至 2024-01-21）
### 总体进度
- 总任务数：23
- 已完成：8（34.8%）
- 进行中：12（52.2%）
- 阻塞：3（13.0%）
### 重点任务状态
#### 移动端登录问题修复 [进行中 - 70%]
- 负责人：李四
- 预期完成：2024-01-25
- 当前状态：已定位到超时配置问题，正在优化重试逻辑
#### 首页加载速度优化 [进行中 - 45%]
- 负责人：王五
- 预期完成：2024-02-01
- 当前状态：完成首屏资源懒加载，LCP 指标下降 40%
### 阻塞事项
1. 第三方支付接口文档缺失，导致支付模块开发暂停
- 阻塞人：赵六
- 需要协调：商务部门联系支付服务商获取文档
### 下周计划
- [ ] 完成移动端登录问题修复
- [ ] 启动图片 CDN 迁移项目
- [ ] 评审 Q2 需求池
---
报告生成时间：2024-01-21 18:00
实战教程：一步步掌握项目使用
现在让我们通过一个完整的实战案例来学习如何使用这个项目。
场景设定
假设你是一个电商团队的负责人，需要使用这个工具来管理本周的开发任务。团队本周有三项重点工作：修复一个严重的支付 Bug、优化首页加载速度、准备下周的活动页面。
步骤一：创建项目结构
首先初始化项目的目录结构：
# 创建主目录
mkdir -p my-planning-project
cd my-planning-project
# 创建标准目录结构
mkdir -p plans tasks requirements configs reports
# 创建本周的规划目录
mkdir -p plans/2024/01/week3
mkdir -p tasks/active tasks/completed
mkdir -p requirements/incoming requirements/reviewed requirements/approved
如果你想快速初始化，可以使用项目自带的脚手架命令：
planning-files init my-new-project
cd my-new-project
planning-files setup --template standard
这会自动创建标准的目录结构和示例文件。
步骤二：提交第一个需求
假设产品经理通过企业微信告诉你：“用户反馈支付时偶尔会失败，要尽快处理。”你把这个需求写入文件：
# requirements/incoming/payment-bug-001.txt
## 需求描述
用户反馈在支付环节偶发失败，具体表现为：选择支付方式后，页面一直转圈，最终提示“支付超时，请重试”。
根据后台日志分析，每天的失败率约为 2-3%，但在高峰期失败率会上升到 8% 左右。
这个问题严重影响用户体验，需要优先处理。
## 问题复现步骤
1. 选择商品并加入购物车
2. 点击结算进入支付页面
3. 选择任意支付方式（微信/支付宝/银行卡）
4. 完成支付密码验证
5. 约 30% 的概率会出现转圈后超时
## 影响范围
- 日均受影响用户：约 500 人
- 直接损失估算：每日约 1 万元订单金额
- 用户投诉量：本周已收到 23 起相关投诉
## 提交信息
- 提交人：产品经理 - 李明
- 提交时间：2024-01-15 09:30
- 紧急程度：高
## 备注
这个问题在上周才出现，怀疑与上周三的服务器迁移有关。
运维同事已经排查过网络和服务器负载，没有发现明显异常。
保存文件后，系统会自动检测到新需求，并将其加入处理队列。
步骤三：AI 自动解析与分类
运行解析命令，让 AI 分析新提交的需求：
planning-files parse requirements/incoming/payment-bug-001.txt
AI 会输出解析结果：
=== 需求解析结果 ===
文件：requirements/incoming/payment-bug-001.txt
提取的任务信息：
┌─────────────────────┬──────────────────────────────────┐
│ 任务名称 │ 修复支付超时偶发失败问题 │
│ 优先级 │ P0（紧急/高影响） │
│ 预估工作量 │ 2-3 人天 │
│ 负责人 │ 未指定 │
│ 截止日期 │ 建议 3 天内 │
│ 技术标签 │ payment, backend, bugfix │
│ 问题严重程度 │ 高（影响营收） │
└─────────────────────┴──────────────────────────────────┘
建议操作：
1. 立即指派给后端团队处理
2. 同步通知运维关注服务器指标
3. 添加到本周 Sprint 的紧急修复通道
是否将此任务添加到任务列表？[Y/n]
输入 Y 确认，任务会被创建并移动到 tasks/active 目录。
步骤四：创建任务详情文件
为每个任务创建详细的任务文件，包含更完整的信息：
# tasks/active/PAY-2024-001-支付超时修复.txt
## 任务基本信息
任务编号：PAY-2024-001
任务名称：修复支付超时偶发失败问题
任务状态：进行中
创建时间：2024-01-15 10:00
更新时间：2024-01-15 14:30
负责人：王开发
预计完成：2024-01-17
## 任务描述
用户在使用微信支付、支付宝或银行卡支付时，约 30% 的概率会出现支付超时。
问题于 2024-01-13 开始出现，疑似与服务器迁移相关。
## 技术分析
### 可能原因
1. 支付网关连接池配置不当，高并发时连接耗尽
2. 网络层面的超时设置过短
3. 后端服务与支付接口的响应时间异常
4. 数据库查询性能下降
### 已执行的排查
- [x] 检查服务器负载：正常
- [x] 检查网络连通性：正常
- [x] 检查支付网关状态：正常
- [ ] 深入分析支付日志：进行中
## 解决方案
### 方案 A：增加超时时间和重试机制
```python
**payment_config.py**
**支付配置优化**
PAYMENT_CONFIG = {
"timeout": 30, # 从 15 秒增加到 30 秒
"retry_times": 3, # 增加重试次数
"retry_interval": 2, # 重试间隔 2 秒
"connection_pool_size": 100, # 增加连接池大小
}
方案 B：异步支付通知处理
**将同步的通知处理改为异步**
@async_task
def handle_payment_callback(order_id: str, status: str):
**异步处理支付回调，避免阻塞**
payment_service.process(order_id, status)
测试计划
- [ ] 在测试环境模拟高并发支付场景
- [ ] 验证超时重试机制正常工作
- [ ] 执行完整的回归测试
- [ ] 准备灰度发布方案
相关文档
- 支付日志分析：docs/payment-logs-20240115.txt
- 服务器迁移记录：docs/server-migration-20240113.md
- 支付接口文档：docs/payment-api-spec.pdf
进度更新
2024-01-15 10:00
任务创建，开始问题分析
2024-01-15 12:00
完成日志初步分析，发现超时主要发生在支付网关响应环节
2024-01-15 14:30
定位到连接池配置问题，开始编写修复代码
**步骤五：管理多个相关任务**
假设支付问题需要拆分为多个子任务，你可以使用项目的任务分解功能：
```python
planning-files split PAY-2024-001 \
--subtasks "日志分析,代码修复,测试验证,灰度发布,全量上线"
这会创建以下子任务文件：
# tasks/active/PAY-2024-001-01-日志分析.txt
# tasks/active/PAY-2024-001-02-代码修复.txt
# tasks/active/PAY-2024-001-03-测试验证.txt
# tasks/active/PAY-2024-001-04-灰度发布.txt
# tasks/active/PAY-2024-001-05-全量上线.txt
每个子任务文件都包含父任务的引用链接，方便追踪：
# tasks/active/PAY-2024-001-02-代码修复.txt
父任务：tasks/active/PAY-2024-001-支付超时修复.txt
## 当前任务：代码修复
状态：[ ] 待完成
... 其他内容
步骤六：任务状态更新
当你完成某个子任务后，更新状态：
# 方法一：直接编辑文件，将状态标记为完成
# 状态：进行中 -> 已完成
# 方法二：使用命令行快速更新
planning-files update PAY-2024-001-02 \
--status completed \
--note "已完成支付配置优化和重试机制实现"
更新后，系统会自动计算父任务的整体进度：
# tasks/active/PAY-2024-001-支付超时修复.txt 中的进度摘要
任务进度：██████░░░░░░░░░░░░░░░░░░░░ 30%
子任务进度：
├── [✓] 日志分析（100%）
├── [✓] 代码修复（100%）
├── [ ] 测试验证（0%） ← 当前
├── [ ] 灰度发布（0%）
└── [ ] 全量上线（0%）
步骤七：生成进度报告
在周五的团队会议上，你想生成一份本周的工作报告：
planning-files report weekly \
--period 2024-W03 \
--output reports/weekly/2024-W03-report.md \
--include-metrics
报告生成后，你可以查看本周的完整进度：
# reports/weekly/2024-W03-report.md
## 本周开发团队工作报告
报告周期：2024-01-15 至 2024-01-19
生成时间：2024-01-19 17:00
=== 执行摘要 ===
本周共处理 3 个紧急任务，5 个常规任务。
紧急任务完成率：100%
常规任务完成率：80%
整体效率评分：85/100
=== 重点任务 ===
#### 支付超时修复 [✓ 已完成]
- 完成时间：2024-01-17 18:00（提前 1 天）
- 负责人：王开发
- 成果：支付失败率从 8% 降至 0.2%，高峰期稳定在 0.5% 以下
- 技术方案：增加超时时间 + 重试机制 + 连接池优化
#### 首页加载优化 [进行中 - 60%]
- 预计完成：2024-01-22
- 负责人：赵前端
- 成果：LCP 从 4.2s 优化至 2.8s，CDN 迁移完成 80%
#### 活动页面开发 [进行中 - 40%]
- 预计完成：2024-01-26
- 负责人：孙设计 + 张前端
- 成果：完成设计评审，进入前端开发阶段
=== 团队贡献 ===
- 王开发：处理 3 个紧急 Bug，效率评分 95
- 赵前端：完成性能优化 2 项，效率评分 88
- 孙设计：产出设计稿 5 套，效率评分 90
=== 阻塞事项 ===
1. 第三方 API 文档缺失（不影响主线进度）
2. 测试环境服务器磁盘空间不足（运维已安排扩容）
=== 下周计划 ===
优先级 P0：
- [ ] 完成首页优化并上线
- [ ] 活动页第一版开发
优先级 P1：
- [ ] 用户反馈系统优化
- [ ] 订单导出功能开发
---
报告由 planning-with-files 自动生成
常见使用场景
场景一：创业公司快速迭代
小团队（3-5 人）可以使用这个项目建立轻量级的需求管理流程：
# 每日站会的任务板文件
# plans/daily/2024-01-19-standup.md
## 2024-01-19 站会记录
### 今日计划
| 任务 | 负责人 | 预计工时 | 优先级 |
|------|--------|----------|--------|
| 完成活动页 Banner 设计 | 小李 | 2h | P1 |
| 修复搜索结果页排序 Bug | 小王 | 3h | P0 |
| 评审第三方登录接口 | 小张 | 1h | P2 |
### 昨日完成
- [✓] 用户反馈表单样式调整
- [✓] 支付成功页文案优化
- [✓] 测试环境部署配置
### blockers（阻塞事项）
- 等待产品经理确认活动页配色方案
场景二：跨部门协作
大型项目中，需求可能来自多个部门。使用文件作为统一入口，可以让协作更顺畅：
# requirements/incoming/跨部门-财务系统对接.txt
## 需求标题
对接财务系统，实现订单自动记账
## 发起部门
财务部
## 协调部门
技术部、产品部
## 需求背景
当前财务需要手动将每日订单导出后导入财务系统，
每天耗时约 2 小时，且容易出错。
预计对接后，可节省 80% 的人工操作时间。
## 功能要求
1. 每日凌晨自动同步昨日订单数据
2. 支持订单金额、退款金额的自动分类
3. 生成财务系统可识别的导入文件
4. 保留 30 天的历史数据供对账使用
## 约束条件
- 必须保证数据准确性，财务相关操作不容出错
- 接口需要通过财务部的安全审计
- 必须在月底前完成，以支持月度结算
## 审批流程
- [x] 财务总监审批
- [x] 技术总监审批
- [ ] CTO 最终审批
场景三：个人项目管理和知识积累
即使是一个人做项目，也可以用这个工具来保持清晰的项目状态：
# 个人项目：开发一个博客系统
# tasks/active/blog-v1-milestones.md
## 博客系统开发里程碑
### 已完成
- [✓] 需求分析和原型设计
- [✓] 技术选型（FastAPI + Vue3）
- [✓] 数据库设计
- [✓] 用户认证模块
- [✓] 文章 CRUD 功能
### 进行中
- [ ] 评论系统开发 [60%]
- 完成：评论列表、发布评论
- 待做：敏感词过滤、回复通知
### 待开发
- [ ] 标签和分类系统
- [ ] 搜索功能
- [ ] SEO 优化
- [ ] 性能优化
- [ ] 上线部署
### 经验总结
#### 2024-01-15：关于数据库设计
这次设计文章表时，踩了一个坑：
最初把标签设计成逗号分隔的字符串，结果查询效率很低。
后来拆分成独立的标签表和多对多关联表，性能提升了 10 倍。
教训：多对多关系尽早拆分，不要为了省事走捷径。
#### 2024-01-10：关于技术选型
最初纠结用 Django 还是 FastAPI。
最终选择 FastAPI 的理由：
- 异步支持更好，未来扩展方便
- 自动生成 OpenAPI 文档，开发体验棒
- 项目规模不需要 Django 的重量级功能
---
## 最佳实践与技巧
### 文件命名规范
良好的命名习惯能让项目管理更加高效。建议采用以下命名模式：
```python
**需求文件：描述-类型-编号.txt**
**示例**
requirements/incoming/用户反馈-登录问题-001.txt
requirements/incoming/bug报告-支付超时-002.txt
requirements/approved/活动页面开发-产品-2024-001.txt
**任务文件：类型-编号-简短描述.txt**
**示例**
tasks/active/TASK-2024-001-登录模块优化.txt
tasks/completed/TASK-2024-002-数据库迁移.txt
**规划文件：类型-时间-版本.txt**
**示例**
plans/2024/Q1-sprint-1.md
plans/2024/Q1-sprint-1-retrospective.md
利用模板加速创建
为常用场景创建模板，减少重复工作：
**.planning-templates/bug-fix.txt**
**Bug 报告模板**
**基本信息**
- 任务编号：{id}
- 严重程度：{severity}
- 发现时间：{date}
- 发现人：{reporter}
**问题描述**
{problem_description}
**复现步骤**
1.
2.
3.
**环境信息**
- 操作系统：
- 浏览器版本：
- APP 版本：
**期望行为**
{expected_behavior}
**实际行为**
{actual_behavior}
**日志/截图**
{logs_or_screenshots}
**初步分析**
{preliminary_analysis}
使用时：
planning-files create --template bug-fix \
--vars "id=BUG-001,severity=high,date=2024-01-15"
自动化工作流
结合 CI/CD 和文件监控系统，可以实现自动化的任务流转：
**.github/workflows/planning-automation.yaml**
name: Planning Automation
on:
push:
paths:
- 'requirements/**'
- 'tasks/**'
jobs:
process-new-items:
runs-on: ubuntu-latest
steps:
- name: 检出代码
uses: actions/checkout@v4
- name: 检查新需求
run: |
planning-files check-new \
--directory requirements/incoming \
--action notify
- name: 更新任务状态
run: |
planning-files sync \
--source tasks \
--target project-management-tool
- name: 生成每日报告
if: github.event_name == 'schedule'
run: |
planning-files report daily \
--output reports/daily/$(date +%Y-%m-%d).md
与 AI 的高效交互
项目中集成了 AI 能力，可以帮助你完成多种任务：
**向 AI 询问任务建议**
planning-files ask "这个支付 Bug 应该怎么排查？优先检查哪些点？"
**让 AI 帮你估算工作量**
planning-files estimate --task PAY-2024-001 --model gpt-4
**让 AI 帮你写代码**
planning-files generate code \
--task "为支付模块添加超时重试机制" \
--language python \
--framework fastapi
备份与同步策略
重要的工作文件需要做好备份：
**定期备份到云存储**
**.scripts/backup.sh**
#!/bin/bash
DATE=$(date +%Y%m%d_%H%M%S)
BACKUP_DIR="/path/to/backups"
PROJECT_DIR="/path/to/your/planning-project"
**创建备份**
tar -czf "$BACKUP_DIR/planning_backup_$DATE.tar.gz" \
-C "$PROJECT_DIR" \
plans tasks requirements configs
**保留最近 30 天的备份**
find "$BACKUP_DIR" -name "planning_backup_*.tar.gz" \
-mtime +30 -delete
**同步到云存储（示例使用 rclone）**
rclone copy "$BACKUP_DIR/planning_backup_$DATE.tar.gz" \
remote:my-planning-backups/
echo "备份完成：$DATE"
进阶功能：自定义与扩展
配置自定义工作流
项目支持定义自己的业务流程：
**configs/workflows.yaml**
workflows:
bug_fix:
name: Bug 修复流程
stages:
- name: 问题确认
required_fields: [severity, environment]
auto_assign: tech_lead
- name: 原因分析
required_fields: [root_cause]
time_limit: 4h
- name: 代码修复
required_fields: [solution]
required_approvals: 1
- name: 测试验证
required_fields: [test_result]
required_approvals: 2
- name: 发布上线
auto_notify: [qa_team, product_manager]
require_sign_off: true
feature_request:
name: 功能需求流程
stages:
- name: 需求提交
template: feature-template.txt
- name: 产品评审
required_approvals: 1
approvers: [product_manager]
- name: 技术评审
required_approvals: 1
approvers: [tech_lead]
- name: 开发排期
required_fields: [estimate, assignee, deadline]
- name: 开发实现
progress_tracking: true
- name: 测试验收
required_approvals: 2
- name: 发布上线
auto_generate_changelog: true
集成第三方工具
项目可以与多种工具集成：
**configs/integrations.yaml**
integrations:
**GitHub 集成**
github:
enabled: true
repository: your-org/your-repo
auto_create_issue: true
sync_labels: true
issue_template: "tasks/active/{task_id}.txt"
**Slack 集成**
slack:
enabled: true
webhook_url: $SLACK_WEBHOOK_URL
channel: "#project-updates"
notify_on:
- new_task
- task_completed
- blocked_task
- weekly_report
**Jira 集成（如果使用企业版）**
jira:
enabled: false
site_url: https://your-company.atlassian.net
project_key: PLANNING
sync_direction: bidirectional
**Notion 集成**
notion:
enabled: false
api_key: $NOTION_API_KEY
database_id: your-database-id
sync_fields:
- name
- status
- assignee
- due_date
自定义 AI 提示词
根据你的业务场景，定制 AI 的行为：
**configs/ai-prompts.yaml**
prompts:
**任务优先级判断**
priority_judgment: |
作为一名经验丰富的项目经理，请评估以下任务的优先级。
任务描述：{task_description}
影响范围：{impact_scope}
紧急程度：{urgency}
截止日期：{deadline}
请从以下维度给出评分（1-10分）：
1. 业务价值
2. 紧急程度
3. 技术复杂度
4. 依赖关系
最终给出 P0/P1/P2/P3 的优先级建议及理由。
**任务拆分建议**
task_breakdown: |
请将以下大型任务拆分为可执行的小任务。
原始任务：{original_task}
团队规模：{team_size}
可用时间：{available_time}
请给出：
1. 任务拆分结果（包含每个子任务的工作量和依赖关系）
2. 推荐的执行顺序
3. 潜在的风险点和应对建议
**周报生成**
weekly_report: |
基于以下任务数据，生成一份专业的周报。
完成的任务：{completed_tasks}
进行中的任务：{in_progress_tasks}
阻塞的任务：{blocked_tasks}
请生成包含以下内容的报告：
1. 执行摘要（3-5 句话）
2. 本周亮点成就
3. 正在进行的工作
4. 阻塞事项及建议
5. 下周计划
6. 需要协调的资源
常见问题与解决方案
问题一：文件太多难以管理
当项目规模增大后，文件数量会迅速增长。解决方案是善用子目录和搜索功能：
**按日期归档**
planning-files archive --older-than 30d --target plans/archive/2024/
**按状态归档**
planning-files archive --status completed --target tasks/completed/
**搜索特定任务**
planning-files search "支付" --directory tasks/
planning-files search "2024-01" --directory plans/
planning-files search --tag bug --directory requirements/
问题二：多人协作时的冲突
当多人同时编辑同一个文件时，可能产生冲突。建议的做法：
**1. 使用细粒度的任务分配，避免多人编辑同一文件**
**2. 利用 Git 的分支功能**
git checkout -b feature/payment-fix
**... 编辑任务文件**
git checkout master
git merge feature/payment-fix
**3. 使用文件锁（需要配置）**
planning-files lock TASK-2024-001 --user alice
**其他用户尝试编辑时会收到提示**
planning-files lock TASK-2024-001
**Error: 文件已被 Alice 锁定**
问题三：AI 解析结果不准确
如果 AI 的解析结果不符合预期，可以：
**1. 提供更详细的上下文**
**在文件开头添加更明确的说明**
**任务类型：bug 修复**
**优先级判定：高（因为影响营收）**
**关键约束：必须兼容 Safari 14+**
**2. 调整 AI 提示词**
**编辑 configs/ai-prompts.yaml 中的解析提示词**
**3. 提供示例文件让 AI 学习**
planning-files learn --from examples/bug-reports/
问题四：如何处理紧急插入的需求
当有紧急需求插入时：
**1. 使用紧急标记**
**在 requirements/incoming 创建时添加标记**
**requirements/urgent/支付系统故障-20240115.txt**
**2. 快速创建任务**
planning-files urgent-create \
--title "紧急修复" \
--severity P0 \
--assignee 王开发 \
--deadline "today"
**3. 自动推送到任务列表顶部**
planning-files prioritize URGENT-2024-001 --top
总结与资源链接
OthmanAdi/planning-with-files 为文件驱动的 AI 规划提供了一个优秀的解决方案。通过将所有信息以文件形式管理，它实现了信息的完整性、可追溯性和协作便利性。
这个项目的核心价值在于：
简单而强大：不需要复杂的安装和配置，用最常见的文件操作就能管理整个项目。
AI 加持：借助 AI 的能力，自动解析、分类、排序，大大减少人工整理的工作量。
高度可扩展：无论是自定义工作流、集成第三方工具还是调整 AI 行为，都能轻松实现。
团队友好：文件天然支持版本控制和协作，适合各种规模的团队使用。
如果你对这个项目感兴趣，可以进一步探索以下资源：
项目地址：
– GitHub 仓库：https://github.com/OthmanAdi/planning-with-files
– 官方文档：查看仓库中的 README.md 和 docs/ 目录
相关工具推荐：
如果你觉得文件管理方式很适合你，也可以了解以下相关项目：
任务管理类：
– Taskipie：一个轻量级的 Python 任务管理工具
– Taskwarrior：命令行任务管理工具的经典之作
– Todo.txt：极简主义的基于文本的任务管理
AI 规划类：
– LangChain：构建 AI 应用的基础框架，可用于构建更复杂的 AI 规划系统
– AutoGPT：自主 AI 任务的实验性项目
– GPT Engineer：使用 AI 生成代码的项目生成器
团队协作类：
– Plane：开源的项目管理工具，支持自定义工作流
– Plane 的文件导入功能可以与 planning-with-files 配合使用
– Vikunja：另一个开源的任务管理应用，API 设计优秀
版本控制与文件管理：
– Obsidian：基于 Markdown 的笔记工具，与文件驱动的理念高度契合
– GitBook：团队文档协作工具
– Notion API：如果你使用 Notion，可以通过 API 与各种工具集成
开始使用 OthmanAdi/planning-with-files 吧，你会发现原来项目管理可以如此简单。从今天起，让文件成为你的得力助手，让 AI 帮你处理繁琐的整理工作，你只需要专注于真正重要的事情：解决问题，创造价值。
“`
评论区