dsh-workspace-journal

工作区日志插件（v0.3.0）：让模型把阶段性结论、决策与复盘持久化到人类可读的 Markdown 日志，跨会话可查。与 dsh-plugin-todo（短期任务）、dsh-session-exporter（会话导出）形成完整的记忆工作流。

安装

npm install dsh-workspace-journal

工具

log_entry

| 参数 | 类型 | 说明 | |------|------|------| | body | string | 必填，条目正文（≤2000 字符；记录结论而非流水账，长文请落盘正式文档） | | tags | array | 可选标签（≤10 个，禁止 , ] 字符） |

写入 <cwd>/.journal/YYYY-MM.md，格式：

### 2026-09-13 14:30:05 [release,v0.1.0]
发布 v0.1.0 到 npm

按月分文件、纯 Markdown，人类可直接查看与手改——手改后的内容也能被工具读回（解析按 ### 时间戳 块切分，空正文条目自动忽略，乱文本不崩溃）。

read_journal

| 参数 | 类型 | 说明 | |------|------|------| | since / until | string | 日期/月份范围（2026-09-01 或 2026-09），until 含当天 | | tag | string | 标签精确过滤 | | keyword | string | 关键词过滤（大小写不敏感） | | regex | string | 正则表达式过滤（如 release|hotfix；与 keyword 同时给出时取交集） | | scope | string | 搜索范围：body / tags / id，多个用逗号分隔；默认全部 | | caseSensitive | boolean | 正则是否区分大小写，默认 false | | limit | number | 默认 20，上限 100 |

最新在前倒序返回；无过滤时查最近 12 个月。

export_journal

按日期范围导出日志，支持 Markdown 与 JSON，可选择落盘或直接返回内容。

| 参数 | 类型 | 说明 | |------|------|------| | since / until | string | 日期/月份范围（2026-09-01 或 2026-09），until 含当天 | | tag / keyword / regex / scope | - | 与 read_journal 语义一致 | | format | string | markdown（默认）或 json | | order | string | asc（时间正序，默认）或 desc（最新在前） | | output | string | 可选输出路径（相对路径，必须位于当前工作目录内）；不传则返回内容 |

Markdown 导出带范围/条数/生成时间的头部，JSON 导出为 { generatedAt, range, filters, count, entries } 结构，便于程序处理。

// 导出本月日志到文件（JSON）
await export_journal({ since: "2026-09", format: "json", output: "out/journal.json" })

// 只导出带 decision 标签的条目（Markdown，最新在前）
await export_journal({ tag: "decision", order: "desc" })

典型工作流

• 阶段收尾时：log_entry({ body: "结论……", tags: ["decision", "v0.2.0"] })
• 新会话开工时：read_journal({ tag: "decision", limit: 10 }) 快速恢复上下文
• 月末复盘：read_journal({ since: "2026-09-01", keyword: "发布" })

限制

• 存储 = 工作目录 .journal/；换目录即换日志（有意设计：日志跟随工作区）
• 单条正文 2000 字符上限（防流水账）；输入错误如实报错不静默
• 零 npm 依赖

测试

插件包含完整的测试套件，覆盖所有核心功能和边界情况。

版本历史

0.3.0（2026-09-30）

• 新增 export_journal 工具：按日期范围导出 Markdown / JSON，支持 tag / keyword / regex 过滤、正倒序与落盘
• read_journal 新增 regex、scope、caseSensitive：支持正则表达式搜索与按正文/标签/ID 限定搜索范围
• 抽取统一的筛选与月份加载逻辑，read 与 export 共用
• 测试增至 45 项断言

0.2.0（2026-09-13）

• 新增 journal_stats 工具：条目统计概览
• 新增 delete_entries 工具：按 id / timestamp / before 三种方式删除
• 条目唯一 ID（时间戳 #hex 后缀），修复同秒写入误删问题

典型场景

项目开发场景

• 版本发布：发布新版本时记录 log_entry({ body: "v1.2.0 发布完成，包含新功能：A、B、C", tags: ["release", "v1.2.0"] })
• 技术决策：架构调整时记录决策原因 log_entry({ body: "决定将数据库从 MySQL 迁移到 PostgreSQL，原因：更好的 JSON 支持", tags: ["decision", "database"] })
• 问题排查：解决复杂问题时记录关键发现 log_entry({ body: "发现内存泄漏原因：循环引用导致的未释放事件监听器", tags: ["debug", "memory"] })

学习研究场景

• 知识总结：学习新技术后记录要点 log_entry({ body: "React Hooks 最佳实践：1. 避免在循环中使用 2. 依赖数组要完整", tags: ["learning", "react"] })
• 论文阅读：阅读论文后记录核心观点 log_entry({ body: "这篇论文提出的注意力机制解决了长序列依赖问题，但计算复杂度较高", tags: ["paper", "nlp"] })

团队协作场景

• 会议纪要：重要会议后记录决议事项 log_entry({ body: "团队决议：下周开始采用新的代码规范，所有新代码必须通过 ESLint 检查", tags: ["meeting", "decision"] })
• 项目复盘：项目阶段性结束后总结经验教训 log_entry({ body: "本次项目延期原因：需求变更频繁，下次需要加强需求评审环节", tags: ["retrospective", "project"] })

个人成长场景

• 工作总结：每天工作结束时记录重要成果和待办事项 log_entry({ body: "完成用户认证模块开发，明天开始处理支付集成", tags: ["daily", "progress"] })
• 技能提升：学习新技术时记录心得体会 log_entry({ body: "今天学习了 TypeScript 高级类型，掌握了条件类型和映射类型的使用方法", tags: ["skill", "typescript"] })

其他插件集成说明

| 协作插件 | 集成方式 | |---|---| | dsh-plugin-todo | 待办事项沉淀到工作日志，形成「记录 → 跟进」闭环 | | dsh-fs-inspector | 结合目录检查确认日志涉及的文件状态 | | dsh-session-exporter | 会话导出后可归档进工作日志 | | dsh-plugin-timer | 定时任务到期后由本插件留痕 |

FAQ

基础使用

Q: 日志文件存储在哪里？
A: 日志存储在当前工作目录的 .journal/ 文件夹中，按月分文件（格式：YYYY-MM.md）。日志跟随工作区，切换目录会创建新的日志文件。

Q: 如何查看历史日志？
A: 使用 read_journal() 工具，支持多种过滤方式：

• 按时间范围：read_journal({ since: "2026-09-01", until: "2026-09-30" })
• 按标签：read_journal({ tag: "decision" })
• 按关键词：read_journal({ keyword: "发布" })
• 组合过滤：read_journal({ since: "2026-09-01", tag: "release" })

Q: 可以编辑或删除日志吗？
A: 可以通过两种方式：

1. 直接编辑文件：.journal/YYYY-MM.md 是纯 Markdown 文件，可直接用文本编辑器修改
2. 使用工具删除：delete_entries() 支持按时间戳精确删除或按时间范围批量删除

Q: 日志条目有大小限制吗？
A: 单条日志正文限制 2000 字符，这是为了鼓励记录精炼的结论而非长篇流水账。长内容建议单独保存为文档，然后在日志中引用。

技术细节

Q: 日志格式是什么？
A: 采用人类可读的 Markdown 格式：

### 2026-09-13 14:30:05 [release,v0.1.0] #abc123
发布 v0.1.0 到 npm

每条记录包含时间戳、可选标签、唯一 ID 和正文。

Q: 如何处理同秒写入？
A: 每条记录都会生成唯一的时间戳（毫秒级精度 + 随机后缀），避免同秒写入冲突。删除操作建议使用 ID 而非时间戳。

Q: 日志文件会自动清理吗？
A: 不会自动清理，但提供了 delete_entries() 工具支持手动清理。建议定期清理旧日志以节省存储空间。

集成使用

Q: 如何与其他插件配合使用？
A: 与以下插件形成完整的工作流：

• dsh-plugin-todo：短期任务管理，完成后记录到日志
• dsh-session-exporter：会话导出，与日志形成互补
• dsh-plugin-calculator：复杂计算时记录计算过程和结果

Q: 可以在 CI/CD 流程中使用吗？
A: 可以，日志文件是纯文本格式，适合在 CI/CD 流程中记录构建、部署等关键步骤。建议在关键操作前后记录状态。

安全边界

数据安全

• 存储位置：日志仅存储在当前工作目录的 .journal/ 文件夹中，不会访问系统其他目录
• 文件权限：使用当前进程的文件系统权限，遵循操作系统的安全策略
• 内容验证：所有输入都会进行格式验证和字符过滤，防止注入攻击

使用限制

• 字符限制：单条日志正文最多 2000 字符，防止内存溢出和文件过大
• 标签限制：最多 10 个标签，每个标签禁止包含 , 和 ] 字符
• 时间范围：读取操作默认限制在最近 12 个月，防止查询过大的历史数据
• 输出截断：单次输出最多 8000 字符，防止终端溢出

隐私保护

• 本地存储：所有日志数据都存储在本地，不会上传到任何服务器
• 无网络依赖：插件零网络依赖，确保数据安全
• 格式透明：使用标准 Markdown 格式，便于备份和迁移

源码及发布地址

源码地址

• GitHub: https://github.com/your-username/dsh-plugins/tree/main/dsh-workspace-journal

发布地址

• NPM: https://www.npmjs.com/package/dsh-workspace-journal
• 版本: 当前最新版本 v0.2.0
• 许可证: MIT

安装方式

# 从 NPM 安装
npm install dsh-workspace-journal

Roadmap

v0.4.0 计划功能

• 标签管理增强

  • 支持标签分类和层级结构
  • 标签统计和趋势分析
  • 标签搜索建议和自动补全

• 导出功能（续）

  • [x] 按日期范围导出 Markdown —— 0.3.0 已实现
  • [x] 导出为 JSON —— 0.3.0 已实现
  • [ ] 导出为 PDF 格式便于分享

• 多日志文件支持

  • 支持创建多个日志文件（如：work.log、personal.log、project.log）
  • 日志文件分组和切换功能
  • 跨日志文件搜索和统计

• 增强搜索

  • [x] 全文搜索（scope 可选正文/标签/ID）—— 0.3.0 已实现
  • [x] 正则表达式搜索 —— 0.3.0 已实现
  • [ ] 模糊搜索和相似度匹配

v0.5.0 远景规划

• Web 界面：提供可视化的日志查看和管理界面
• 协作功能：支持多用户协作编辑和评论
• AI 集成：与 AI 助手深度集成，提供智能摘要和洞察
• 插件扩展：支持第三方插件扩展功能

长期愿景

• 成为 DeepSeek Harness 生态中的核心记忆管理工具
• 支持更多格式和场景的日志记录需求
• 提供企业级的日志管理和分析功能