Project Development Assistant

工程开发助理 (Project Development Assistant)

设计原则：随时可中断，随时可继续。日志静默写入，聊天只回一行摘要。

核心功能

防刷屏核心规则：

• log / progress / generate 默认静默，只写文件不输出
• 加 --show 才在聊天显示摘要
• 所有脚本输出控制在 3行以内

触发条件（精确激活）

仅在以下明确指令时激活：

不激活： 闲聊、问候、模糊请求与项目无关的内容

一、新建项目

用户：「新建项目」「创建项目」

python <skill>/scripts/log_project.py -a new -p <项目路径> -n <项目名称>

创建内容：

项目/
├── logs/                     # 每日开发日志
├── sessions/                 # 会话归档目录
│   └── session_latest.md     # 始终指向最新归档
├── configs/
├── firmware/
├── docs/
├── hardware/
├── references/
├── tools/
└── PROJECT_INFO.md

状态文件： .project_state.json（结构化状态，替代散乱日志读取）

二、继续项目

用户：「继续项目」「接着上次」

执行顺序（不可跳过）：

# 1. 项目结构
python <skill>/scripts/log_project.py -a structure -p <项目路径>

# 2. 状态文件（结构化，一行摘要）
python <skill>/scripts/log_project.py -a state -p <项目路径>

# 3. 最新日志（只显示最后8条）
python <skill>/scripts/log_project.py -a read -p <项目路径>

回复模板（限3句）：

📊 项目名 | 🔄 进行中
   当前：xxx
   问题：xxx（若有）

三、记录进度

用户：「记录 xxx」

# 默认静默写入，不打扰聊天
python <skill>/scripts/log_project.py -a log -p <项目路径> -m "<消息>" -c <类别>

# 需要显示确认时加 --show
python <skill>/scripts/log_project.py -a log -p <项目路径> -m "<消息>" -c INFO --show

日志类别：

四、更新状态

用户：「项目状态改为进行中」「当前任务是xxx」

# 更新状态（静默）
python <skill>/scripts/log_project.py -a state -p <项目路径> -s 进行中 -t "开发LCD驱动"

# 添加问题（可多次 -i）
python <skill>/scripts/log_project.py -a state -p <项目路径> -i "SPI引脚冲突"

# 添加下一步（可多次 --step）
python <skill>/scripts/log_project.py -a state -p <项目路径> --step "修复SPI" --step "测试显示"

五、项目简报

# 生成所有项目简报（静默）
python <skill>/scripts/task_briefing.py -a generate

# 显示摘要（--show 才输出）
python <skill>/scripts/task_briefing.py -a generate --show

# 查看单个项目状态
python <skill>/scripts/task_briefing.py -a status -p <项目名>

# 检查需要恢复的任务
python <skill>/scripts/task_briefing.py -a check-resume

# 列出所有项目
python <skill>/scripts/task_briefing.py -a list

简报存储： briefings/*.json（结构化，不在聊天刷屏）

六、快速命令参考

# === 新建 ===
python log_project.py -a new -p <路径> -n <名称>

# === 记录（静默）===
python log_project.py -a log -p <路径> -m <消息> -c INFO

# === 记录（显示）===
python log_project.py -a log -p <路径> -m <消息> -c INFO --show

# === 状态 ===
python log_project.py -a state -p <路径>          # 读取
python log_project.py -a state -p <路径> -s 进行中 -t "任务名"  # 更新

# === 读取 ===
python log_project.py -a read -p <路径>            # 日志（最后20条）
python log_project.py -a progress -p <路径>       # 状态+日志摘要
python log_project.py -a structure -p <路径>      # 结构（限深2层）
python log_project.py -a list -p <路径>            # 日志列表

# === 简报 ===
python task_briefing.py -a generate --show        # 生成+显示
python task_briefing.py -a status -p <项目名>     # 单项目状态
python task_briefing.py -a check-resume           # 检查需恢复任务

七、防刷屏规则

原则：一个开发动作 → 最多一行聊天回复

八、状态文件格式

.project_state.json 结构：

{
  "project": "项目名",
  "status": "进行中",
  "current_task": "当前任务描述",
  "last_updated": "2026-03-22 22:00:00",
  "summary": "一句话状态",
  "open_issues": ["问题1", "问题2"],
  "next_steps": ["下一步1", "下一步2"],
  "milestones": []
}

九、会话精简与上下文管理

问题分析

单次会话对话过长会导致：

• 上下文窗口逐渐填满，AI 响应变慢变贵
• 早期上下文被"挤出"，丢失项目背景
• 新会话无法感知上一个会话的结论

解决方案：会话归档协议（Session Archival Protocol）

核心思路：用结构化文件代替对话记录来传递上下文。

归档触发时机

满足以下任一条件时，主动触发归档：

归档操作步骤

当检测到需要归档时，执行以下步骤：

Step 1：生成归档摘要

用户：「归档当前会话」

主动用日志记录归档内容，不依赖 AI 总结：

# 用时间戳+类别记录归档点
python log_project.py -a log -p <项目路径> -m "【会话归档】<项目名> - 第N次会话" -c PROGRESS --show

Step 2：写入会话归档文件

在 sessions/ 目录下创建归档文件：

项目/sessions/session_<日期>.md

文件格式：

# 会话归档 - <项目名>
日期：<YYYY-MM-DD>
会话数：<N条消息>

## 背景
<项目的技术栈、目标、当前阶段>

## 达成的结论
1. <结论1>
2. <结论2>

## 未解决的问题
- <问题1>
- <问题2>

## 当前任务
- 当前：<正在做的事>
- 下一步：<准备做的事>

## 关键文件/代码位置
- <文件路径>：<说明>

Step 3：更新项目状态

# 读取当前状态
python log_project.py -a state -p <项目路径>

# 更新当前任务
python log_project.py -a state -p <项目路径> -s 进行中 -t "<当前任务>"

Step 4：开启新会话

在 AI 端发起 /new 或 /reset，清除上下文。

Step 5：新会话恢复

继续项目时，读取最近的归档文件恢复上下文：

# 读取最新归档
Get-Content "项目/sessions/session_*.md" | Sort-Object LastWriteTime -Descending | Select-Object -First 1

新会话开场白模板：

请读取 D:\项目路径\sessions\ 目录下最新的归档文件，了解项目当前状态和历史结论。

上下文管理原则

会话目录结构

项目/
├── sessions/              # 会话归档目录
│   ├── session_2026-03-20.md
│   ├── session_2026-03-22.md
│   └── session_latest.md  # 始终指向最新归档

与其他工具的关系

会话对话
    ↓（归档时写入）
sessions/session_YYYY-MM-DD.md
    ↓（新会话时读取）
.project_state.json ← 由 log_project.py 管理
    ↓（cron 监控读取）
briefings/*.json

相关参考

• 工作流详细说明：references/workflow.md
• 简报存储：briefings/*.json
• 会话归档存储：sessions/session_*.md