项目看板 Notoonex/dsh-project-board

DSH Project Board

把「项目结构 + 待办 + 决策」收进一套可追踪的记录系统：一棵节点树、两份文件、右侧栏一键查看。

浅色模式深色模式

它解决什么

- 待办和决策散落在聊天、文档、看板里，过两周就找不到；
- 看板按「阶段」分节，但每天是按「产品部位」干活，找不全一个页面的上下文；
- 决策只记结论不记理由，三个月后无法判断是否还成立；
- 汇总数字手写，改一处忘一处。

这套系统用三个约束解决：

1. 节点树：## 20 首页，节点 = 持久的产品面/领域，不是任务、不是阶段；
2. 双轨记录：进度看板放任务，决策台账放决策，共用同一套节点 ID；
3. 派生视图：进度、未完成、待拍板全部算出来，不手写。

右侧栏

- 索引 chips + 互斥手风琴：一次只展开一个节点；
- 搜索、仅未完成、待拍板过滤；
- 决策按节点分组，点开底部抽屉看理由/备选/影响/复审；
- 浅色 / 深色自动跟随 DSH 主题。

安装

作为 DSH 插件（推荐）

dsh plugin --profile web add @notoonex/dsh-project-board

从源码安装：dsh plugin --profile web add github:Notoonex/dsh-project-board

重启 DSH 后，右侧栏会出现「项目看板」。
插件会自动把 skill 安装到 ~/.dsh/skills/project-board/，并托管本地 board server。

只装 Skill

在 dsh-skills-marketplace 里添加本仓库，稀疏路径填 skill。
Skill 本身不依赖插件，只要有 markdown 和 Node 就能用。

配置

| 环境变量 | 默认 | 说明 |
| DSH_PROJECTS_DIR | ~/Documents/Projects | 项目根目录，每个子目录一个项目 |
| DSH_PROJECT_BOARD_PORT | 自动 | 可选；不设时从 8791 起自动找空闲端口 |

如果你的项目在别的目录，启动 DSH 前设置 DSH_PROJECTS_DIR。
不设端口时，server 会自动找空闲端口，前端也会自动探测，不需要手动配。

目录结构

$DSH_PROJECTS_DIR/
└── my-app/
├── my-app 进度看板.md ├── my-app 决策台账.md ├── 踩坑.md # 可选，只放教训 └── README.md # 可选，定位/背景

规则：

- 每个项目各恰好一个 * 进度看板.md 和 * 决策台账.md；
- 两份文件 stem 必须一致，frontmatter 的 project: 必须等于 stem；
- 不建第三份记录，不用表格承载可勾选任务。

文件格式

进度看板

schema: project-board/1
project: my-app
archetype: web-app
nodes:
"00": 治理 "10": 全局与架构 "20": 首页 "90": 归档

20 首页范围：首屏 / 导航 / 视觉

- [ ] 首屏文案定稿 · 验收: 3 秒内说清产品是什么 · 关联: D-20-01
- [ ] [[首屏是否放演示视频]] 等 owner 拍板
- [x] 四屏结构定型 abc1234

决策台账

schema: decision-log/1
project: my-app

D-20-01 首屏采用单 CTA
- 节点: 20 首页
- 状态: 生效
- 日期: 2026-10-24
- 可逆性: 可逆
- 理由: 首屏只保留一个动作，降低选择成本
- 备选: 双 CTA / 无 CTA
- 影响: 20
- 复审: 上线两周看转化率

决策 ID 自带节点：D-20-01 = 节点 20 的第 1 条。台账扁平按 ID 排序，天然按节点分组，不需要复制章节骨架。

Skill

Skill 在 skill/：

- references/init.md：首次接入与迁移；
- references/operate.md：日常写任务/决策；
- references/schema.md：完整字段与编号规则；
- references/packs/：web / business / life 域包；
- scripts/lint.mjs：跨文件校验；
- scripts/scan-legacy.mjs：旧看板只读扫描，输出 mapping 草稿。

node "$DSH_SKILL_DIR/scripts/lint.mjs" "$DSH_PROJECTS_DIR/my-app"

安全

- 只监听 127.0.0.1，公网访问不到；
- 非本机来源的请求直接 403，不只是“不给读”；
- project 参数按目录白名单校验，拒绝路径穿越；
- 只读写项目目录内的 * 进度看板.md / * 决策台账.md；
- 勾选回写优先按任务 ID，其次按「节点 + 任务文本」定位，不依赖行号；
- 本地 token：首次启动自动生成，客户端自动携带；同一台机器上的其他页面没有 token，调用会被 401 拒绝。

Token

- 首次启动生成 ~/.dsh/project-board/token（权限 600）；
- 插件启动时把 token 写进已安装的 client/client.js；
- 客户端所有 API 请求带 X-Project-Board-Token；
- /api/health 不校验 token，只用于端口探测；
- 如果侧栏报 401：重载 DSH；或删除 token 文件后重启 DSH，让插件重新生成并注入。

这是一次性自动配置，不需要你输入任何东西。
只有一种情况会失败：插件安装目录本身是只读的（例如全局 npm 安装）。用 dsh plugin add 装到 profile 目录通常是可写的。

更新

- 增量更新：只覆盖有变化的文件；
- 你新增的文件会保留；
- 你改过的文件会保留（日志提示 kept local skill edit）；
- 上游删除、且你没改过的文件会被删除；
- 想强制全量：删掉 ~/.dsh/skills/project-board/ 或其中的 .manifest.json，重启 DSH。

写入定位

侧栏勾选不再按行号硬写：

1. 任务有 [T-<节点>-<序号>] → 按 ID 找；
2. 没有 ID → 按「节点 + 任务文本」找；
3. 都找不到 → 返回 409，让前端刷新，不会误勾别的任务；
4. 勾选完成只加/去 删除线，不改任务原文（链接、反引号、加粗都保留）。

开发

npm test

测试包含：

- lint 正常/异常 fixture；
- board server 的 board/decisions API；
- 路径穿越拦截；
- CORS 远程来源拒绝 / 本地来源放行。

兼容

- DSH（Cordis）插件；
- 纯 markdown，Obsidian 可直接打开；
- Skill 部分对 Codex / Claude 也可复用。

发布

上架步骤见 PUBLISHING.md。

License

MIT

DSH Project Board 把项目结构、待办和决策汇成一套可追踪的系统：一棵节点树、两个 Markdown 文件，外加一个右侧栏视图。

它解决什么问题

- 待办和决策散落在聊天、文档和看板里。
- 看板按阶段分组，你却按产品面来干活。
- 决策只记结论，不记理由。
- 汇总数字靠手工维护，越跑越偏。

三条约束：

1. 节点树 —— ## 20 Home；节点是长期存在的产品面或领域，不是任务，也不是阶段。
2. 两份记录 —— 进度看板放任务，决策台账放决策；两者共用节点 ID。
3. 派生视图 —— 进度、未完成项、待决事项全部算出来，绝不手写。

右侧栏

- 索引 chip 加互斥手风琴：一次只展开一个节点。
- 搜索、「只看未完成」、「待决策」筛选。
- 决策按节点分组；底部抽屉展示理由、备选方案、影响和复盘。
- 明暗模式跟随 DSH 主题。

安装

作为 DSH 插件安装（推荐）：

dsh plugin --profile web add @notoonex/dsh-project-board

源码安装：dsh plugin --profile web add github:Notoonex/dsh-project-board

重启 DSH，右侧栏会出现「Project Board」标签页。插件会把内置技能装到 ~/.dsh/skills/project-board/，并管理本地 board server。

只装技能：把本仓库加进 dsh-skills-marketplace，sparse 路径填 skill。

配置

| 变量 | 默认值 | 说明 |
| DSH_PROJECTS_DIR | ~/Documents/Projects | 项目根目录；每个项目一个子目录 |
| DSH_PROJECT_BOARD_PORT | 自动 | 可选固定端口；不填则探测 8791–8800 |
| DSH_PROJECT_BOARD_SKILL_DIR | ~/.dsh/skills/project-board | 高级：覆盖技能安装路径 |

项目结构

$DSH_PROJECTS_DIR/
└── my-app/
├── my-app 进度看板.md ├── my-app 决策台账.md ├── 踩坑.md # optional └── README.md # optional

文件后缀故意用中文（进度看板.md、决策台账.md）。frontmatter 里的 project: 必须与文件名主干一致。

文件格式

进度看板

schema: project-board/1
project: my-app
archetype: web-app
nodes:
"00": 治理 "20": 首页

20 首页范围：首屏 / 导航 / 视觉

- [ ] 首屏文案定稿 · 验收: 3 秒内说清产品是什么 · 关联: D-20-01
- [ ] [[首屏是否放演示视频]] 等 owner 拍板
- [x] 四屏结构定型 abc1234

决策台账 markdown

schema: decision-log/1
project: my-app

D-20-01 首屏采用单 CTA

- 节点: 20 首页
- 状态: 生效
- 日期: 2026-10-24
- 可逆性: 可逆
- 理由: 首屏只保留一个动作，降低选择成本
- 备选: 双 CTA / 无 CTA
- 影响: 20
- 复审: 上线两周看转化率

字段名用中文（节点、状态、日期……），因为解析器和技能都靠它们识别。

Token

- 首次启动时生成，路径 ~/.dsh/project-board/token（权限 600）。
- 插件把它注入安装好的 client/client.js。
- 每个 API 请求都带 X-Project-Board-Token；/api/health 公开，用于探测端口。
- 遇到 401？重载 DSH，或删掉 token 文件再重启 DSH。
- 这是一次性自动配置，不需要用户输入。唯一的失败情形是插件安装目录只读。

更新

- 内置技能增量更新。
- 本地新增的文件保留；本地改动也保留（kept local skill edit）。
- 上游删除的文件，只有没改过才删。
- 想强制全量刷新，删掉 ~/.dsh/skills/project-board/ 或其中的 .manifest.json。

回写

- 优先用任务 ID [T-<node>-<seq>]；没有 ID 时，服务端按节点加任务文本匹配。
- 任务已变更时，服务端返回 409，客户端刷新；绝不会误切到别的任务。
- 切换完成状态只增删 ~~；链接、行内代码和加粗都保留。

安全

- 只监听 127.0.0.1。
- 非本地 Origin 一律 403 拒绝。
- project 按目录白名单校验；路径穿越直接拒绝。
- 只读写项目目录内的 * 进度看板.md / * 决策台账.md。
- 自动生成 token；远程页面和没带 token 的本地页面都返回 401。

开发 bash
npm test

覆盖 lint 测试样例、看板与决策 API、401、403、路径穿越、按内容切换以及 Markdown 保留。

兼容性

- DSH（Cordis）插件。
- 纯 Markdown，可用 Obsidian 打开。
- 技能由 Markdown 加 Node 脚本组成，其他智能体也能复用。

发布

见 PUBLISHING.md。

许可证

MIT