# Project Development Assistant

> Project Development Assistant — structured logging + issue tracking with anti-spam design. Trigger ONLY when user explicitly says new project, continue project, or log progress. NOT for casual chat. Developer: 杨荣才 (yangrongcai141@gmail.com)

- Skill: `lord1egypt/project-development-assistant` (Agent Skill)
- Install (CLI): `npx skillmds@latest add lord1egypt/project-development-assistant`
- Raw SKILL.md: https://api.skillmd.com/api/skills/lord1egypt/project-development-assistant/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: Lord1Egypt (https://skillmd.com/u/lord1egypt)
- Updated: 2026-09-08
- Page: https://skillmd.com/skills/lord1egypt/project-development-assistant

---


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

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

---

## 核心功能

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

**防刷屏核心规则：**
- `log` / `progress` / `generate` 默认静默，只写文件不输出
- 加 `--show` 才在聊天显示摘要
- 所有脚本输出控制在 **3行以内**

---

## 触发条件（精确激活）

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

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

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

---

## 一、新建项目

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

```bash
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`（结构化状态，替代散乱日志读取）

---

## 二、继续项目

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

**执行顺序（不可跳过）：**

```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句）：**
```
📊 项目名 | 🔄 进行中
   当前：xxx
   问题：xxx（若有）
```

---

## 三、记录进度

```
用户：「记录 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 | 重要里程碑达成 | 「固件烧录成功」 |

---

## 四、更新状态

```
用户：「项目状态改为进行中」「当前任务是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：生成归档摘要**

```
用户：「归档当前会话」
```

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

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

**Step 2：写入会话归档文件**

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

```
项目/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
```

**新会话开场白模板：**
```
请读取 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](references/workflow.md)
- 简报存储：`briefings/*.json`
- 会话归档存储：`sessions/session_*.md`