工程开发助理 (Project Development Assistant)#

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

---

核心功能#

功能说明📁 项目初始化创建标准项目结构 + 状态文件📝 日志管理静默写入文件，聊天只回一行确认📊 状态追踪结构化状态文件（.project_state.json）🔍 进度简报生成项目快照（JSON），聊天只回关键信息⚠️ 问题记录自动提取 open_issues，标注阻塞点

防刷屏核心规则：

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

---

触发条件（精确激活）#

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

用户说激活动作「新建项目」「创建项目」项目初始化「继续项目」「接着上次」读取状态 + 最新日志摘要「项目进度」「状态如何」显示简报摘要「记录」「日志」「标记」+ 某事写入日志（静默）「项目结构」「看下结构」显示结构（限深2层）

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

---

一、新建项目#

text

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

bash

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

创建内容：

text

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

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

---

二、继续项目#

text

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

执行顺序（不可跳过）：

bash

# 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句）：

text

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

---

三、记录进度#

text

用户：「记录 xxx」

bash

# 默认静默写入，不打扰聊天
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

日志类别：

类别触发时机示例INFO任务开始/完成、状态更新「开始开发驱动」「编译成功」ERROR任何错误「编译失败」「连接超时」FIXED解决方案「已解决引脚冲突」PROGRESS进行中里程碑「完成了屏幕驱动」WARNING潜在风险「闪存空间不足」SUCCESS重要里程碑达成「固件烧录成功」

---

四、更新状态#

text

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

bash

# 更新状态（静默）
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 "测试显示"

---

五、项目简报#

bash

# 生成所有项目简报（静默）
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（结构化，不在聊天刷屏）

---

六、快速命令参考#

bash

# === 新建 ===
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           # 检查需恢复任务

---

七、防刷屏规则#

操作默认行为聊天输出新建项目静默创建✅ 1行确认记录日志静默写入❌ 无输出记录日志+--show写入+显示✅ 1行摘要读取日志显示摘要≤3行进度摘要显示状态≤5行生成简报静默写文件✅ 1行统计生成简报+--show写+显示≤N项目行

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

---

八、状态文件格式#

.project_state.json 结构：

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）#

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

归档触发时机

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

触发条件说明会话消息数 > 50 条对话密度已高，需要整理AI 主动提示上下文接近上限模型响应开始变慢或重复项目进入新阶段完成一个里程碑，准备下一阶段重要结论已形成决定/方案已确认，需要存档

归档操作步骤

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

Step 1：生成归档摘要

text

用户：「归档当前会话」

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

bash

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

Step 2：写入会话归档文件

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

text

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

文件格式：

markdown

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

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

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

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

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

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

Step 3：更新项目状态

bash

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

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

Step 4：开启新会话

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

Step 5：新会话恢复

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

bash

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

新会话开场白模板：

text

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

上下文管理原则

做法原因细节操作写日志，不在聊天反复确认日志是文件不占上下文结论性对话主动归档防止结论被后续对话挤出按功能阶段开新会话每个阶段独立，减少上下文纠缠归档文件命名含日期便于快速找到最新归档

会话目录结构

text

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

与其他工具的关系

text

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

---

相关参考#

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