ai-board 0.1.0__tar.gz

ai_board-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ai-board contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ai_board-0.1.0/PKG-INFO

@@ -0,0 +1,258 @@
+Metadata-Version: 2.4
+Name: ai-board
+Version: 0.1.0
+Summary: A lightweight local planning board CLI for AI-assisted projects.
+Author: ai-board contributors
+License-Expression: MIT
+Keywords: ai,agents,planning,cli,kanban
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: build; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Dynamic: license-file
+
+# ai-board
+
+给 AI agent 用的本地计划看板。它把需求、排期、正在改的文件范围、验收结果和遗留问题记录下来，让 AI 接手项目时不用只靠聊天记录猜。
+
+[English](https://github.com/dev-null-sec/ai-board/blob/v0.1.0/README_en.md) | 中文
+
+<p align="center">
+  <img alt="Python 3.10+" src="https://img.shields.io/badge/Python-3.10%2B-3776AB?logo=python&logoColor=white">
+  <img alt="CLI ai-board" src="https://img.shields.io/badge/CLI-ai--board-0B1F4D">
+  <img alt="License MIT" src="https://img.shields.io/badge/License-MIT-green">
+</p>
+
+![ai-board logo](https://raw.githubusercontent.com/dev-null-sec/ai-board/v0.1.0/assets/ai-board.png)
+
+当前正式版本：`v0.1.0`。
+
+## 为什么做这个
+
+AI 写代码时，很多混乱不是代码本身造成的，而是项目状态没有一个稳定地方保存。
+
+一个需求刚说完，AI 可能立刻开改；又插进来一个 bug，它也继续改。几轮之后，原来的计划在哪里、当前任务算不算做完、哪些文件已经被另一个会话碰过，就很容易散在聊天记录里。
+
+`ai-board` 只处理这类项目事实：需求进不进看板、排到哪一批、谁在做、scope 是哪些文件、验收跑了什么、还有什么没收尾。聊天继续负责讨论细节，看板负责留下可恢复的状态。
+
+它不是 Jira，也不是 Web 项目管理系统。现在就是一个本地 CLI，一个 `.ai-board/board.json`，再生成两份 Markdown 看板给人和 AI 读。
+
+## 最短路径
+
+一般不需要人手动敲一串命令，直接把这段给 AI：
+
+```text
+请安装 ai-board 并接手当前项目：
+1. 优先用 pipx install ai-board 安装用户级 CLI。
+2. 如果 pipx 不可用，再用 uv tool install ai-board。
+3. 安装后运行 ai-board onboard --init-if-missing。
+4. 按该 agent 的 skill 安装方式，把 https://github.com/dev-null-sec/ai-board.git 里的 skills/ai-board/SKILL.md 放到对应 agent 的 skills 目录；除非该 agent 已经安装过这个 skill。
+```
+
+自己安装时：
+
+```powershell
+pipx install ai-board
+```
+
+没有 `pipx` 但有 `uv`：
+
+```powershell
+uv tool install ai-board
+```
+
+想试 GitHub 上的当前源码版：
+
+```powershell
+pipx install "git+https://github.com/dev-null-sec/ai-board.git"
+```
+
+## 人和 AI 怎么配合
+
+`ai-board` 更适合这样用：人说清楚意图，AI 负责安装、接手、排期、启动任务、记录验收和归档。人不用记命令，提示词也不该写成长规则；短、准、能触发流程就够。
+
+### 第一次接手
+
+给 AI 这段提示词：
+
+```text
+用 ai-board 接手这个项目。
+先 onboard；信息不够就问我，不要猜方向或直接编码。
+```
+
+这句话会让 AI 自己处理安装、初始化和读取内置指南。空项目先问目标、用户和第一版范围；已有项目先整理状态，再把后续开发放进看板。
+
+### 提新需求
+
+平时不要让 AI 直接“顺手改一下”。更稳的说法是：
+
+```text
+把这个需求进 ai-board。
+判断它是否属于当前任务；不属于就排期，别直接开改。
+```
+
+需要立刻处理时，可以说得更明确：
+
+```text
+这个问题优先处理。
+先写入 ai-board 并说明插队原因，再 start、声明 scope、修改和验收。
+```
+
+### 多 agent 开发
+
+默认是单 agent 轻量模式。如果确实要同时开两个 AI 会话，先让其中一个会话启用多 agent：
+
+```text
+开启 ai-board 多 agent 协作。
+每个会话先 claim 身份；改前查 scope，收到 notice 先收口。
+```
+
+### 看进度
+
+问 AI 就行：
+
+```text
+看 ai-board：现在做什么？下一步做什么？
+```
+
+AI 背后会用 `status`、`next`、`show`、`doctor` 这些命令读状态。命令细节留给 agent，人的工作是确认方向、优先级和验收口径。
+
+## 它保存哪些东西
+
+| 内容 | 放在哪里 |
+| --- | --- |
+| 任务、状态、负责人、scope、验收结果 | `.ai-board/board.json` |
+| 当前看板 | `docs/计划看板.md` |
+| 归档看板 | `docs/归档计划看板.md` |
+| 操作历史 | `.ai-board/events.jsonl` |
+| agent notice | `.ai-board/messages.jsonl` |
+
+`board.json` 是唯一写入源，Markdown 只是生成视图。任务状态、依赖、scope、验收这些字段需要被程序读取、排序和校验，放在 JSON 里更稳；Markdown 留给人读。
+
+## 几个默认选择
+
+| 设计 | 当前做法 |
+| --- | --- |
+| 单 agent 开发 | 默认轻量，不强制处理多 agent notice 和 scope 冲突。 |
+| 多 agent 协作 | 项目级可选开关，默认关闭。需要并行开发时开启。 |
+| git | 默认 `git_integration=suggest`，没有 git 时提示初始化，但不会静默 `git init`。 |
+| 看板语言 | 默认中文，可改成 `en-US`。 |
+| scope | 记录文件或小目录，不做语义级代码冲突判断。 |
+
+多 agent 开启方式：
+
+```powershell
+ai-board config set multi_agent_enabled true
+```
+
+开启后，重叠 scope 会被拦住，`next --agent` 会显示 notice，`complete` / `archive` 会提醒未收口消息。单 agent 开发时，它不会强制你天天看 notice、处理 inbox 或被 active scope 冲突拦住。
+
+git 强制模式：
+
+```powershell
+ai-board config set git_integration required
+```
+
+临时实验目录可以关闭 git 检查：
+
+```powershell
+ai-board config set git_integration off
+```
+
+## 常见问题
+
+<details>
+<summary><strong>为什么不用 Markdown 直接管理任务？</strong></summary>
+
+Markdown 很适合读，不适合当结构化状态源。任务状态、负责人、scope、依赖、验收结果这些字段需要稳定读写。格式一旦被人或 AI 改散，工具就很难判断哪些是内容，哪些是结构。
+
+所以 `ai-board` 用 JSON 存状态，再生成 Markdown 看板。
+
+</details>
+
+<details>
+<summary><strong>Markdown 看板可以手动改吗？</strong></summary>
+
+不建议。下一次 CLI 写操作或 `ai-board render` 会重新生成 Markdown，手改内容可能被覆盖。改任务状态、负责人、scope、验收结果时走 CLI。
+
+</details>
+
+<details>
+<summary><strong>为什么不自动 git init？</strong></summary>
+
+AI 开发最好有可回滚点，但项目根目录、父级仓库、临时目录、大文件、密钥和已有未完成改动都可能需要确认。`ai-board` 会提醒，不会静默初始化 git，也不会自动提交用户已有改动。
+
+</details>
+
+<details>
+<summary><strong>多 agent 防冲突能防到什么程度？</strong></summary>
+
+只能防路径重叠。比如一个任务锁了 `src/api`，另一个任务要改 `src/api/handler.py`，开启多 agent 后会被拦住。
+
+它不理解两个不同文件之间的业务耦合，也不是跨机器强锁。真正并行开发时，scope 还是要写窄，任务边界也要写清楚。
+
+</details>
+
+<details>
+<summary><strong>只能给 Codex 用吗？</strong></summary>
+
+不是。仓库里带了 Codex 可读的 skill stub，但 CLI 本身只是普通命令行工具。Claude、其他 agent，或者人手动敲命令都能用。关键是让 agent 先读 `ai-board skills get core`，按当前版本的规则操作。
+
+</details>
+
+## 当前边界
+
+| 已支持 | 暂不做 |
+| --- | --- |
+| 本地 CLI | Web 登录 |
+| JSON 真相源 | 云同步 |
+| Markdown 生成视图 | 手写 Markdown 当数据库 |
+| 事件日志和 `history` | 完整审计系统 |
+| `doctor` 项目自检 | 语义级代码冲突判断 |
+| git-first 提示和 required 门禁 | 静默初始化 git 或自动提交 |
+| 可选多 agent 路径级 scope 防撞 | 跨机器协作锁 |
+| 轻量 agent notice | 实时聊天系统 |
+
+## 项目结构
+
+```text
+src/ai_board/          CLI 核心
+skills/ai-board/       给 AI agent 的 discovery skill
+tests/                 测试
+docs/                  这个项目自己的计划和状态文档
+examples/demo-project/ 示例项目
+```
+
+## 开发
+
+```powershell
+uv sync
+uv run python -m unittest discover -s tests
+uv run --with ruff ruff check .
+```
+
+本地安装当前工作区版本：
+
+```powershell
+uv tool install --editable .
+```
+
+发布前检查：
+
+```powershell
+uv run ai-board conflicts --fail-on-conflict
+uv run ai-board doctor --fail-on-issue
+uv run --with build python -m build
+uv run --with twine twine check dist/*
+```
+
+## License
+
+MIT License. See [LICENSE](./LICENSE).

ai_board-0.1.0/README.md

@@ -0,0 +1,238 @@
+# ai-board
+
+给 AI agent 用的本地计划看板。它把需求、排期、正在改的文件范围、验收结果和遗留问题记录下来，让 AI 接手项目时不用只靠聊天记录猜。
+
+[English](https://github.com/dev-null-sec/ai-board/blob/v0.1.0/README_en.md) | 中文
+
+<p align="center">
+  <img alt="Python 3.10+" src="https://img.shields.io/badge/Python-3.10%2B-3776AB?logo=python&logoColor=white">
+  <img alt="CLI ai-board" src="https://img.shields.io/badge/CLI-ai--board-0B1F4D">
+  <img alt="License MIT" src="https://img.shields.io/badge/License-MIT-green">
+</p>
+
+![ai-board logo](https://raw.githubusercontent.com/dev-null-sec/ai-board/v0.1.0/assets/ai-board.png)
+
+当前正式版本：`v0.1.0`。
+
+## 为什么做这个
+
+AI 写代码时，很多混乱不是代码本身造成的，而是项目状态没有一个稳定地方保存。
+
+一个需求刚说完，AI 可能立刻开改；又插进来一个 bug，它也继续改。几轮之后，原来的计划在哪里、当前任务算不算做完、哪些文件已经被另一个会话碰过，就很容易散在聊天记录里。
+
+`ai-board` 只处理这类项目事实：需求进不进看板、排到哪一批、谁在做、scope 是哪些文件、验收跑了什么、还有什么没收尾。聊天继续负责讨论细节，看板负责留下可恢复的状态。
+
+它不是 Jira，也不是 Web 项目管理系统。现在就是一个本地 CLI，一个 `.ai-board/board.json`，再生成两份 Markdown 看板给人和 AI 读。
+
+## 最短路径
+
+一般不需要人手动敲一串命令，直接把这段给 AI：
+
+```text
+请安装 ai-board 并接手当前项目：
+1. 优先用 pipx install ai-board 安装用户级 CLI。
+2. 如果 pipx 不可用，再用 uv tool install ai-board。
+3. 安装后运行 ai-board onboard --init-if-missing。
+4. 按该 agent 的 skill 安装方式，把 https://github.com/dev-null-sec/ai-board.git 里的 skills/ai-board/SKILL.md 放到对应 agent 的 skills 目录；除非该 agent 已经安装过这个 skill。
+```
+
+自己安装时：
+
+```powershell
+pipx install ai-board
+```
+
+没有 `pipx` 但有 `uv`：
+
+```powershell
+uv tool install ai-board
+```
+
+想试 GitHub 上的当前源码版：
+
+```powershell
+pipx install "git+https://github.com/dev-null-sec/ai-board.git"
+```
+
+## 人和 AI 怎么配合
+
+`ai-board` 更适合这样用：人说清楚意图，AI 负责安装、接手、排期、启动任务、记录验收和归档。人不用记命令，提示词也不该写成长规则；短、准、能触发流程就够。
+
+### 第一次接手
+
+给 AI 这段提示词：
+
+```text
+用 ai-board 接手这个项目。
+先 onboard；信息不够就问我，不要猜方向或直接编码。
+```
+
+这句话会让 AI 自己处理安装、初始化和读取内置指南。空项目先问目标、用户和第一版范围；已有项目先整理状态，再把后续开发放进看板。
+
+### 提新需求
+
+平时不要让 AI 直接“顺手改一下”。更稳的说法是：
+
+```text
+把这个需求进 ai-board。
+判断它是否属于当前任务；不属于就排期，别直接开改。
+```
+
+需要立刻处理时，可以说得更明确：
+
+```text
+这个问题优先处理。
+先写入 ai-board 并说明插队原因，再 start、声明 scope、修改和验收。
+```
+
+### 多 agent 开发
+
+默认是单 agent 轻量模式。如果确实要同时开两个 AI 会话，先让其中一个会话启用多 agent：
+
+```text
+开启 ai-board 多 agent 协作。
+每个会话先 claim 身份；改前查 scope，收到 notice 先收口。
+```
+
+### 看进度
+
+问 AI 就行：
+
+```text
+看 ai-board：现在做什么？下一步做什么？
+```
+
+AI 背后会用 `status`、`next`、`show`、`doctor` 这些命令读状态。命令细节留给 agent，人的工作是确认方向、优先级和验收口径。
+
+## 它保存哪些东西
+
+| 内容 | 放在哪里 |
+| --- | --- |
+| 任务、状态、负责人、scope、验收结果 | `.ai-board/board.json` |
+| 当前看板 | `docs/计划看板.md` |
+| 归档看板 | `docs/归档计划看板.md` |
+| 操作历史 | `.ai-board/events.jsonl` |
+| agent notice | `.ai-board/messages.jsonl` |
+
+`board.json` 是唯一写入源，Markdown 只是生成视图。任务状态、依赖、scope、验收这些字段需要被程序读取、排序和校验，放在 JSON 里更稳；Markdown 留给人读。
+
+## 几个默认选择
+
+| 设计 | 当前做法 |
+| --- | --- |
+| 单 agent 开发 | 默认轻量，不强制处理多 agent notice 和 scope 冲突。 |
+| 多 agent 协作 | 项目级可选开关，默认关闭。需要并行开发时开启。 |
+| git | 默认 `git_integration=suggest`，没有 git 时提示初始化，但不会静默 `git init`。 |
+| 看板语言 | 默认中文，可改成 `en-US`。 |
+| scope | 记录文件或小目录，不做语义级代码冲突判断。 |
+
+多 agent 开启方式：
+
+```powershell
+ai-board config set multi_agent_enabled true
+```
+
+开启后，重叠 scope 会被拦住，`next --agent` 会显示 notice，`complete` / `archive` 会提醒未收口消息。单 agent 开发时，它不会强制你天天看 notice、处理 inbox 或被 active scope 冲突拦住。
+
+git 强制模式：
+
+```powershell
+ai-board config set git_integration required
+```
+
+临时实验目录可以关闭 git 检查：
+
+```powershell
+ai-board config set git_integration off
+```
+
+## 常见问题
+
+<details>
+<summary><strong>为什么不用 Markdown 直接管理任务？</strong></summary>
+
+Markdown 很适合读，不适合当结构化状态源。任务状态、负责人、scope、依赖、验收结果这些字段需要稳定读写。格式一旦被人或 AI 改散，工具就很难判断哪些是内容，哪些是结构。
+
+所以 `ai-board` 用 JSON 存状态，再生成 Markdown 看板。
+
+</details>
+
+<details>
+<summary><strong>Markdown 看板可以手动改吗？</strong></summary>
+
+不建议。下一次 CLI 写操作或 `ai-board render` 会重新生成 Markdown，手改内容可能被覆盖。改任务状态、负责人、scope、验收结果时走 CLI。
+
+</details>
+
+<details>
+<summary><strong>为什么不自动 git init？</strong></summary>
+
+AI 开发最好有可回滚点，但项目根目录、父级仓库、临时目录、大文件、密钥和已有未完成改动都可能需要确认。`ai-board` 会提醒，不会静默初始化 git，也不会自动提交用户已有改动。
+
+</details>
+
+<details>
+<summary><strong>多 agent 防冲突能防到什么程度？</strong></summary>
+
+只能防路径重叠。比如一个任务锁了 `src/api`，另一个任务要改 `src/api/handler.py`，开启多 agent 后会被拦住。
+
+它不理解两个不同文件之间的业务耦合，也不是跨机器强锁。真正并行开发时，scope 还是要写窄，任务边界也要写清楚。
+
+</details>
+
+<details>
+<summary><strong>只能给 Codex 用吗？</strong></summary>
+
+不是。仓库里带了 Codex 可读的 skill stub，但 CLI 本身只是普通命令行工具。Claude、其他 agent，或者人手动敲命令都能用。关键是让 agent 先读 `ai-board skills get core`，按当前版本的规则操作。
+
+</details>
+
+## 当前边界
+
+| 已支持 | 暂不做 |
+| --- | --- |
+| 本地 CLI | Web 登录 |
+| JSON 真相源 | 云同步 |
+| Markdown 生成视图 | 手写 Markdown 当数据库 |
+| 事件日志和 `history` | 完整审计系统 |
+| `doctor` 项目自检 | 语义级代码冲突判断 |
+| git-first 提示和 required 门禁 | 静默初始化 git 或自动提交 |
+| 可选多 agent 路径级 scope 防撞 | 跨机器协作锁 |
+| 轻量 agent notice | 实时聊天系统 |
+
+## 项目结构
+
+```text
+src/ai_board/          CLI 核心
+skills/ai-board/       给 AI agent 的 discovery skill
+tests/                 测试
+docs/                  这个项目自己的计划和状态文档
+examples/demo-project/ 示例项目
+```
+
+## 开发
+
+```powershell
+uv sync
+uv run python -m unittest discover -s tests
+uv run --with ruff ruff check .
+```
+
+本地安装当前工作区版本：
+
+```powershell
+uv tool install --editable .
+```
+
+发布前检查：
+
+```powershell
+uv run ai-board conflicts --fail-on-conflict
+uv run ai-board doctor --fail-on-issue
+uv run --with build python -m build
+uv run --with twine twine check dist/*
+```
+
+## License
+
+MIT License. See [LICENSE](./LICENSE).

ai_board-0.1.0/pyproject.toml

@@ -0,0 +1,37 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "ai-board"
+version = "0.1.0"
+description = "A lightweight local planning board CLI for AI-assisted projects."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [{ name = "ai-board contributors" }]
+keywords = ["ai", "agents", "planning", "cli", "kanban"]
+classifiers = [
+  "Development Status :: 5 - Production/Stable",
+  "Environment :: Console",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+]
+
+[project.scripts]
+ai-board = "ai_board.cli:main"
+
+[project.optional-dependencies]
+dev = ["build", "ruff"]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.ruff]
+line-length = 160
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B"]
+ignore = ["E501"]

ai_board-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

ai_board-0.1.0/src/ai_board/__init__.py

@@ -0,0 +1,3 @@
+"""Lightweight planning board for AI-assisted projects."""
+
+__version__ = "0.1.0"

ai_board-0.1.0/src/ai_board/__main__.py

@@ -0,0 +1,4 @@
+from .cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())