本地看板 rbourgeat/llm-monitor-skill

LLM MONITOR

一个本地优先的看板，用来管理开放笔记、任务和项目跟进。它提供 Python 命令行给智能体用，一个极简的本地 Web UI 给人用，还有一个共享 JSON 存储，每次改动都会标注来源是 AI 还是 human。

UI 只有英文，零依赖，带浅色/深色主题，跑在 127.0.0.1 上。不需要账号、云服务、数据库，也不用装包。

LLM Monitor local kanban board

项目、自定义列、AI/human 来源标注和项目动态，都在同一块本地看板上。

安装

LLM / 智能体 —— 自动安装

有文件系统访问权限的智能体，可以直接从代码检出安装技能，不需要包管理器。先确定 harness 的技能根目录（已安装技能的父目录），只复制运行时文件，然后验证：

SKILL_ROOT="/absolute/path/to/harness/skills" # the harness's skill directory
DEST="$SKILL_ROOT/llm-monitor"
mkdir -p "$DEST"
cp -R SKILL.md README.md kanban.py app ui tests "$DEST/"
python3 "$DEST/kanban.py" doctor

目标文件夹必须叫 llm-monitor，与 SKILL.md 里的 name 保持一致。用这个名字注册或刷新 harness 目录条目；不要装第二份副本，也不要建符号链接。数据主目录（默认 ~/.kanban）在技能之外，同一台机器上的所有安装共用。

人类 —— 手动安装

1. 克隆或下载这个仓库，然后在仓库根目录打开终端。
2. 创建技能目录并复制运行时文件（命令与上面的智能体路径相同，把 SKILL_ROOT 换成你 harness 的技能目录）。
3. 运行 python3 "$DEST/kanban.py" doctor，确认 Python 3.9+ 和数据主目录。
4. 初始化看板一次，然后启动本地 UI：

python3 "$DEST/kanban.py" init
python3 "$DEST/kanban.py" serve --daemon
python3 "$DEST/kanban.py" url

打开打印出来的 127.0.0.1 URL。不需要 pip install、虚拟环境、数据库或云账号；Git 可选，只读，用于项目动态。

发布到 GitHub

仓库已经可以直接用 Git：.gitignore 排除了 Python 缓存、系统元数据、本地看板数据和服务端运行时文件。先创建一个空的 GitHub 仓库，然后把这份检出指向它，推送当前的 main 分支：

git remote add origin git@github.com:<owner>/llm-monitor.git
git push -u origin main

把 <owner> 换成 GitHub 账号或组织。不要提交 ~/.kanban 数据、服务端日志、附件或凭据；它们都留在仓库之外。

功能

- 卡片 —— 创建、编辑、移动、关闭、重新打开、评论、删除；标签、优先级、必填的项目关联、图片/文件附件。
- 完成时间 —— 已关闭的卡片在看板和卡片详情里显示从创建到关闭的耗时。
- 自定义列 —— 添加、重命名、改色、排序、删除（卡片会迁移）；关闭/打开状态决定「关闭」的含义；每列有自己的排序控件。
- 溯源 — 每张卡片都显示创建人、最后编辑人和关闭人。每次改动都记在卡片历史里；顶栏弹窗中有一条最新优先的事件审计记录，区分 AI 与人类活动。
- 筛选 — 全部、人类（最后编辑人）、AI（最后编辑人）、AI 触碰过（任一溯源参与者）、项目筛选和搜索。
- 项目 — 按绝对路径注册本地项目；拖动行调整顺序；仪表盘自动显示进度、git 分支、最后一次提交、脏状态、最近 7 天提交数。
- 自动进度 — 已关闭卡片数除以全部卡片数，四舍五入到整数百分比；卡片创建、删除、移动、关闭、重新打开、更换项目，或某列的关闭状态变化时，都会重新计算。命令行 --progress 编辑是临时覆盖；下一次相关改动会重新计算。
- 时间跟踪 — 把卡片移入 Doing 列会启动该卡片的项目计时器（仅限 AI 移动）；关闭卡片会停止对应计时器。命令行 timer start/stop 仍可用于手动计时。界面里没有计时器控件。
- 智能体简报 — 按优先级排列的未关闭卡片、项目、最近事件和下一步建议的紧凑上下文；下一步建议按优先级挑选卡片，长度接近字符预算上限时截断。
- 安全存储 — 原子保存、备份文件、损坏恢复、建议性文件锁、共享数据主目录。命令行编辑通过服务器变更监视器实时出现在界面里，不靠定时轮询。
- 离线界面 — 不加载远程脚本、字体、样式或导入；图标是本地内联 SVG 集，不是 emoji。明暗主题、自定义下拉菜单和滚动阴影都用本地 CSS/JS 实现。

运行

先确定技能根目录（包含本 README 和 kanban.py 的目录）：

SKILL_ROOT=/absolute/path/to/llm-monitor
KANBAN="$SKILL_ROOT/kanban.py"
python3 "$KANBAN" doctor

初始化默认数据主目录（~/.kanban），启动界面，并打印其 URL：

python3 "$KANBAN" init
python3 "$KANBAN" serve --daemon
python3 "$KANBAN" url

默认 URL 是 http://127.0.0.1:8787；如果端口被占用，服务器会尝试后面九个端口，所以始终用 url 获取权威地址。停止：

python3 "$KANBAN" serve --stop

在子命令前加 --home，或设置 $KANBAN_HOME，可隔离看板：

python3 "$KANBAN" --home "$HOME/.kanban-test" serve --port 8899 --daemon

命令行快速开始

python3 "$KANBAN" brief
python3 "$KANBAN" add "Ship onboarding" --body "Acceptance criteria" --priority high \
--project "/abs/path/to/app" --tags "ui,onboarding"
python3 "$KANBAN" list
python3 "$KANBAN" show c-fcc888
python3 "$KANBAN" edit c-fcc888 --body "Updated context" --note "Clarified scope"
python3 "$KANBAN" move c-fcc888 doing --note "Ready to implement"
python3 "$KANBAN" comment c-fcc888 --text "Tests pass on main"
python3 "$KANBAN" close c-fcc888 --note "Merged in commit abc123"
python3 "$KANBAN" reopen c-fcc888
全局 --json（放在子命令之前）输出机器可读的结果：

python3 "$KANBAN" --json list
python3 "$KANBAN" --json status

溯源模型

| 字段 | 含义 |
| created_by | 创建卡片的操作者（ai 或 human） |
| updated_by | 最后一次修改的操作者 |
| closed_by | 关闭卡片的操作者，未关闭时为空 |
| 卡片 history | 带时间戳的修改记录，含操作者、动作、摘要和字段差异（上限 50 条） |
| 全局 events | 跨卡片、列、项目和计时器的审计流水，最新在前（上限 500 条） |

命令行默认 --actor ai。API 和 UI 的修改一律记为 human。因此 UI 上的徽标能区分 AI 创建、编辑、关闭的工作与人类的工作，历史记录也精确显示改了什么。智能体不得用 --actor human、HTTP API 或 UI 自动化伪造人类溯源。

Web UI

打开 url 打印出的地址。看板支持：

- 在列之间拖动卡片；拖进已关闭的列即关闭卡片。没有注册项目就无法创建卡片。
- 添加、编辑、关闭、重新打开卡片，添加评论，查看含历史和评论的完整详情，从详情弹窗或在创建、编辑卡片时上传图片和文件附件（保存时上传）。
- 添加、编辑、重排、删除列，每列可独立按优先级、更新时间、创建时间或名称排序。删除含卡片的列时会要求指定目标列。
- 用绝对路径注册项目，编辑详情和备注，拖动行调整 Projects 列表顺序，以及 Remove from registry——不会删除文件夹或其中的卡片。左侧 Projects 菜单是紧凑列表，顶部有 All projects 行；选中某个项目后，看板只显示该项目的卡片，下方显示项目详情卡，选中行用项目颜色着色，并成为新建卡片的默认项目。All projects 行清除筛选。
- 项目详情会探测项目自带的文档（README.md、AGENTS.md、SKILL.md、docs/）。存在的文档显示为标签；缺失 README.md/AGENTS.md 时显示红色警告。简报列出找到和缺失的文档，并提示智能体在处理项目卡片前先读这些文档。
- Absolute path 旁的 Browse… 按钮打开宿主系统的原生文件夹选择器（macOS Finder、Linux zenity/kdialog、Windows PowerShell）；浏览器拿不到绝对路径，所以由本地服务器提供。没有可用的原生选择器时，手动输入路径。
- 项目进度自动计算；详情卡和行标签都会显示。UI 没有计时器控件：AI 移动和关闭卡片驱动自动计时。无法运行的 Git 探测会显示红色 git unavailable 徽标，悬停可看完整错误，而不是致命错误文本。
- 筛选和搜索；数据文件变化时视图自动刷新（/api/watch 上的长轮询监听），窗口获得焦点或重新可见时刷新，UI 修改后也刷新。没有固定刷新定时器。
- Settings 顶栏菜单里有浅色/深色主题切换（显示当前主题）和服务器状态（Server on/Server off，配绿点/灰点）。按 Escape 或点击菜单外部即可关闭。
- 最近的 AI/人工事件放在顶栏的 Events 按钮里，不在侧边栏。所有图标都是本地内联 SVG；界面里没有 emoji 或图形字符。
- 浅色/深色主题存在 localStorage；不加载远程资源、字体或网络导入。

界面没有身份验证。只让它监听回环地址，不要暴露到网络。

项目与进度

python3 "$KANBAN" projects add "/abs/path/to/project" --name "Child Learning Game"
python3 "$KANBAN" projects list --git
python3 "$KANBAN" projects edit "Child Learning Game" --note "Core loop works"
python3 "$KANBAN" projects reorder "Music" "Child Learning Game" # pass every project exactly once
python3 "$KANBAN" timer start "Child Learning Game" --note "Implementing scene 2"
python3 "$KANBAN" timer status
python3 "$KANBAN" timer stop
python3 "$KANBAN" activity --project "Child Learning Game"

Git 探测是只读的。进度自动计算（closed cards / all cards，四舍五入）：智能体不得编造完成百分比。projects edit --progress N 会存一个临时手动覆盖值，但下一次卡片/列变更会重新计算。删除项目只会解除卡片与项目的关联，不会删除卡片；项目文件夹永远不会被改动。计时器通常跟随 AI 卡片工作：卡片移入 Doing 时启动该卡片的计时，关闭卡片时停止对应会话。timer start/stop 用于手动命令行会话。

列

python3 "$KANBAN" columns list
python3 "$KANBAN" columns add "QA" --color "#f59e0b"
python3 "$KANBAN" columns edit qa --closed
python3 "$KANBAN" columns edit qa --open
python3 "$KANBAN" columns rm qa --move-to open
python3 "$KANBAN" columns reorder open doing done

把列标记为关闭，会关闭列内所有卡片。删除非空列必须带 --move-to。关闭卡片靠关闭列实现；把卡片移出关闭列会重新打开它。

数据目录

默认 ~/.kanban，可用 $KANBAN_HOME 或 --home 覆盖：

- data.json — 共享看板数据。
- data.json.bak — 上一次保存的备份。
- data.corrupt-<stamp>.json — 发生恢复时保留的损坏文件。
- server.json、server.log、kanban.lock。

保存时先写临时文件，再 fsync 并原子替换；变更操作在支持的环境下会加建议锁。如果 data.json 损坏，存储会从备份恢复，并保留损坏副本。批量改动前请备份整个目录。

测试

cd "$SKILL_ROOT"
python3 tests/smoke.py

标准库冒烟测试使用临时数据目录，覆盖卡片、来源信息、列、项目、项目文档发现、计时器、简报、API（包括文件夹浏览和实时变更监视）、损坏恢复和静态界面服务。它不会碰真实看板。

目录结构

SKILL.md harness 技能清单与智能体规则 README.md 本文件 kanban.py 可移植入口 app/ 模型、存储、卡片、项目、git/docs 探测、简报、命令行、API/server ui/ 静态 HTML/CSS/JS tests/smoke.py 端到端冒烟测试 LICENSE MIT 许可证

技能可移植：把整个目录复制到另一个 harness 的技能根目录即可；只依赖 Python 3.9+ 标准库。kanban.py 会把自己的目录加入 sys.path，因此不依赖 harness 运行时。不要用复制和符号链接两种方式重复安装同一个技能。

许可证

MIT — 见 LICENSE。Copyright (c) 2026 Raphaël Bourgeat。