项目开发助理

Project Development Assistant — structured logging + issue tracking with anti-spam design. Trigger ONLY when user explicitly says new project, continue proje...

Security Scan

The skill is internally coherent for a local project logging/briefing assistant: it reads/writes project files, creates project folders, and generates briefings — it does not request credentials or perform network installs, but it will scan drives and write files in project and skill folders, so review filesystem effects before use.

Purpose & Capability

Name/description (project dev assistant, logging, briefings, anti-spam) match the included scripts: log_project.py, task_briefing.py, task_monitor.py, project_admin.py implement project initialization, structured state, logging, briefings and passive monitoring.

Instruction Scope

SKILL.md and scripts limit actions to filesystem operations (create project folders, write logs, read latest logs, write .project_state.json, save briefings). The skill will scan multiple locations (~/.openclaw/workspace, drive roots like C:, D:, E:, F:, and common 'Projects' folders) to discover projects — this is expected for the purpose but means it reads directory listings and project files across drives. SKILL.md mentions '联网搜索组件信息' (internet search) in the workflow doc, but none of the included scripts perform network access; that's a mismatch to note. Also SKILL.md includes an explicit PowerShell example (Get-Content) — scripts are cross-platform but some examples are Windows-specific.

Install Mechanism

No install specification; this is instruction-plus-scripts. No downloaded or external install steps are present, so nothing is pulled from the network or written to unusual system locations by an installer.

Credentials

No required environment variables, credentials, or config paths are declared or needed. The scripts operate on user-supplied project paths and on predictable places (~/.openclaw/workspace, skill's briefings folder, and scanned drives).

Persistence & Privilege

always is false and the skill does not request elevated platform privileges. It writes files only under project directories and the skill's briefings directory (created under the skill). project_admin may delete briefing files older than 3 days and purge test briefings — this is limited to the skill's briefings directory.

Assessment

What this skill will do: it scans your filesystem for project folders (home workspace and common drive roots), creates a standard project folder structure when asked, writes daily devlog files and a structured .project_state.json, and stores briefings under the skill's briefings directory. It does not require any API keys or network installs. Things to consider before installing: 1) Filesystem access: the code will list directories on C:/, D:/, E:/, F: and ~/.openclaw/workspace to find projects — ensure you are comfortable with that scope and the skill having read access to those locations. 2) Writes and deletions: it will create folders and files in the project path you supply and in the skill's 'briefings' directory; project_admin also removes briefing files older than 3 days and can purge test-named briefings. Back up any important files first. 3) Mismatch note: SKILL.md mentions internet searches for component info, but none of the supplied scripts perform network requests — if you need automatic web lookups, verify how and whether that will be added. 4) Activation: SKILL.md states the skill should only trigger on explicit commands (new project / continue / record etc.). Confirm the agent's invocation policy respects that. If you want stronger safety, run the scripts in a sandboxed environment or inspect/run them manually before enabling autonomous invocation.

工程开发助理 (Project Development Assistant)

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

---

核心功能

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

防刷屏核心规则：

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

---

触发条件（精确激活）

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

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

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

---

一、新建项目

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

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

日志类别：

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

---

四、更新状态

用户：「项目状态改为进行中」「当前任务是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           # 检查需恢复任务

---

七、防刷屏规则

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

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

---

八、状态文件格式

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

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

归档触发时机

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

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

归档操作步骤

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

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