am423/projectsmd

GitHub: am423/projectsmd

这是一个用于AI-人类协作的单文件项目管理CLI工具,通过一个Markdown文件集中管理项目所有信息,解决AI会话间上下文丢失的问题。

Stars: 24 | Forks: 0

# 项目管理md **一个用于智能体-人类协作的单文件项目管理 CLI 工具。** `projectsmd` 是一个单一的二进制文件,用于管理 `project.md` 文件 —— 这个 markdown 文件捕获了项目从开始到结束的所有信息。它让 AI 智能体能够精确地接续上次的工作,无论何时,无论何地,并帮助人类和智能体共同规划、跟踪和执行工作。 无需数据库。无需网络应用。无需外部服务。只需一个文件和一个二进制程序。 ## 存在意义 AI 智能体在构建软件方面日新月异。但存在一个根本性问题:**智能体在会话之间会丢失上下文。** 每次对话重置,智能体都从头开始 —— 它不知道之前决定了什么、构建了什么、什么被阻塞了,以及什么是最重要的。 与此同时,项目信息分散在各个工具中: - 需求存在 Google 文档中 - 决策埋没在 Slack 聊天记录里 - 进度在 Jira 或 Linear 中跟踪 - 架构在白板上草绘 - 经验教训随着会话结束而消失 **`projectsmd` 通过将所有内容置于一个文件中来解决这个问题。** ## 安装 ### 从源码安装(推荐) ``` git clone https://github.com/am423/ProjectsMD.git cd ProjectsMD cargo install --path . ``` ### 从 crates.io 安装 ``` cargo install projectsmd ``` ### 预构建二进制文件 从 [GitHub 发行版](https://github.com/am423/ProjectsMD/releases) 下载: ``` # Linux (x86_64) curl -sL https://github.com/am423/ProjectsMD/releases/latest/download/projectsmd-linux-amd64.tar.gz | tar xz sudo mv projectsmd /usr/local/bin/ # macOS (Apple Silicon) curl -sL https://github.com/am423/ProjectsMD/releases/latest/download/projectsmd-darwin-arm64.tar.gz | tar xz sudo mv projectsmd /usr/local/bin/ ``` ### 验证安装 ``` projectsmd --version ``` ## 教程:你的第一个项目 本指南将带你从零开始,在 5 分钟内创建一个托管项目。 ### 步骤 1:创建一个项目 ``` mkdir my-project && cd my-project projectsmd init ``` 交互式向导会询问你: ``` ProjectsMD — New Project ───────────────────────── Project name: My Web App Owner: Alice Agent (optional): Claude Tags (comma-separated): web, typescript, react What is this project? (2-3 sentences) > A web application for managing personal book collections. > Users can add, rate, and review books. Built with React and TypeScript. Core value (the ONE thing that matters): > Fast, intuitive book management — add a book in under 10 seconds. Constraints (type: value — why, empty line to finish): > Tech Stack: TypeScript + React — team expertise > Performance: Page load under 2 seconds — user retention > ``` 这将创建 `project.md` 文件,并填充所有章节。 ### 步骤 2:了解当前状态 ``` projectsmd status ``` ``` ── Project Status ── Project: My Web App Phase: define Created: 2026-04-29 Updated: 2026-04-29 Requirements: 0 validated, 0 active, 2 out of scope Tasks: 0 done, 3 pending, 0 blocked Decisions: 0 total Sessions: 0 logged ``` ### 步骤 3:添加任务 ``` # 向 BUILD 阶段添加任务 projectsmd task add "Set up React project with Vite" --phase BUILD projectsmd task add "Implement book list component" --phase BUILD projectsmd task add "Add book form with validation" --phase BUILD projectsmd task add "Rating and review system" --phase BUILD projectsmd task add "Local storage persistence" --phase BUILD # 添加验证任务 projectsmd task add "Unit tests for components" --phase VERIFY projectsmd task add "E2E test: add and view book" --phase VERIFY # 查看所有任务 projectsmd task list ``` ### 步骤 4:完成一些工作 开始你的项目工作。当你完成一个任务时: ``` projectsmd task done 1 projectsmd task done 2 ``` 在你做决策时记录下来: ``` projectsmd decide "Use Vite over CRA" --rationale "Faster dev server, better ESM support" ``` 记录你的发现: ``` projectsmd discover "React 19 use() hook simplifies data loading significantly" ``` ### 步骤 5:结束你的会话 ``` projectsmd session ``` 向导会引导你完成: ``` Session Wrap-up ─────────────── Tasks completed this session: 1. Set up React project with Vite 2. Implement book list component Enter completed task numbers (comma-separated): 1, 2 Any decisions made this session? (y/n): y Decision: Use Zustand over Redux for state management Rationale: Simpler API, less boilerplate, sufficient for this scale Session summary (1-2 sentences): > Set up React project with Vite. Implemented book list component with > basic CRUD. Chose Zustand for state management. Updating project.md... ✓ Task 1 marked complete ✓ Task 2 marked complete ✓ Decision logged ✓ Current State updated ✓ Session Log appended ✓ Frontmatter updated ``` ### 步骤 6:恢复下一个会话 下次你回来时: ``` projectsmd next ``` ``` Next action: Task 3 — Add book form with validation Implement a form component with title, author, rating fields. Use React Hook Form with Zod validation. Phase: BUILD | Blockers: None ``` 智能体读取此信息后,就能确切知道该做什么。无需重新解释。 ### 步骤 7:过渡阶段 当所有 BUILD 任务完成后: ``` projectsmd phase transition verify ``` 这将运行演化检查清单: - 将已发布的需求提升为"已验证" - 检查"这是什么"部分是否仍然准确 - 更新项目状态 ### 步骤 8:完成后归档 ``` projectsmd archive --summary "v1.0 released. Book management working with local storage." ``` ## 命令参考 ### `init` — 创建一个新的 project.md 文件 ``` projectsmd init # Interactive wizard projectsmd init --name "my-app" --owner "Alice" projectsmd init --brownfield # For existing codebases projectsmd init --from old-project.md # Import context from file projectsmd init --template custom.md # Use custom template ``` 向导将引导你完成:项目名称、所有者、描述、核心价值和约束条件。它会生成一个完整的 `project.md` 文件,所有章节结构规范。 **标志:** - `--name NAME` — 跳过名称提示 - `--owner OWNER` — 跳过所有者提示 - `--brownfield` — 使用现有项目模板(从现有代码中推断已验证的需求) - `--from FILE` — 从现有文档导入上下文 - `--template FILE` — 使用自定义模板,而非内置默认模板 ### `validate` — 检查是否符合 project.md 规范 ``` projectsmd validate # 示例输出: # ✓ 通过 — 项目符合规范 # 信息 (4): # ℹ 状态:构建 # ℹ 要求:2 项已验证,5 项活跃,5 项超出范围 # ℹ 任务:9 项完成,13 项待处理,0 项阻塞(跨 5 个阶段) # ℹ 决策:共 6 项(4 项良好,2 项待定,0 项待重审) ``` 检查内容包括: - YAML 前置元数据完整性(必填字段、有效状态、ISO 日期) - 所有 6 个必需章节是否存在 - 三级需求生命周期(已验证 / 进行中 / 范围外) - 任务复选框语法 - 关键决策表格式 - 核心价值的简洁性 - 当前状态的完整性 **标志:** - `--strict` — 将警告视为错误 - `--json` — 以 JSON 格式输出 - `--quiet` — 仅输出退出码(0 = 通过,1 = 失败) ### `status` — 显示当前项目状态 ``` projectsmd status # 示例输出: # ── 项目状态 ── # # 项目: 天气命令行界面 # 阶段: 构建 # 创建时间: 2026-04-25 # 更新时间: 2026-04-29 # # 要求: 2 项已验证,5 项活跃,4 项超出范围 # 任务: 9 项完成,18 项待处理,0 项阻塞 # 决策: 共 6 项(4 项良好,2 项待定,0 项待重审) # 会话日志: 4 条已记录 ``` **标志:** - `--json` — 以 JSON 格式输出 - `--compact` — 单行摘要 ### `next` — 显示下一步该做什么 ``` projectsmd next # 示例输出: # 下一步操作:任务 4 — 使用颜色编码进行显示格式化 # # 在 display/format.go 中实现温度到颜色的映射 # 使用 fatih/color 库。 # # 阶段:BUILD | 阻塞因素:无 ``` 读取当前状态和任务列表,以确定最合理的下一步行动。 **标志:** - `--all` — 显示所有待处理任务,而非仅下一个 - `--phase PHASE` — 显示特定阶段的任务 ### `task` — 管理任务 ``` # 列出任务 projectsmd task list # All tasks projectsmd task list --phase BUILD # Tasks in a phase projectsmd task list --pending # Only unfinished tasks # 添加任务 projectsmd task add "Implement auth" # Default: BUILD phase projectsmd task add "Write spec" --phase DEFINE # 完成任务 projectsmd task done 4 # Mark task 4 as done # 阻塞/取消阻塞 projectsmd task block 5 --reason "Waiting on API key approval" projectsmd task unblock 5 ``` 任务自动编号。BUILD 阶段的任务获得顺序编号(任务 1,任务 2,...),便于引用。 ### `decide` — 记录关键决策 ``` projectsmd decide "Use PostgreSQL over MongoDB" \ --rationale "Need relational data and ACID transactions" projectsmd decide "Drop IE11 support" --rationale "Less than 0.1% of traffic" # 设置初始结果 projectsmd decide "Use Vite" --rationale "Faster builds" --outcome good ``` 决策以 markdown 表格的形式记录,包含三列:决策、理由、结果。结果跟踪决策随时间推移是否被证明是正确的: - `good` — ✓ 良好(已证明正确) - `revisit` — ⚠️ 需重新审视(需要重新考虑) - `pending` — — 待定(评估为时过早) ### `discover` — 记录发现 ``` projectsmd discover "OpenWeatherMap returns 401 for invalid keys, not 403" projectsmd discover "Go's net/http already handles connection pooling" ``` 发现用于记录陷阱、变通方法和意外情况。它们与决策不同 —— 发现是观察,而非选择。 ### `phase` — 管理项目阶段 ``` projectsmd phase # Show current phase projectsmd phase --transition design # Transition to design phase projectsmd phase --transition build # Transition to build phase projectsmd phase --transition verify # Transition to verify phase projectsmd phase --transition ship # Transition to ship phase projectsmd phase --transition paused # Pause the project ``` 阶段转换会运行演化检查清单: 1. 已发布的需求 → 提升为"已验证" 2. 失败的需求 → 移至"范围外" 3. 新需求 → 添加到"进行中" 4. "这是什么"部分是否仍然准确? 5. 更新关键决策的结果 有效的阶段:`define`, `design`, `build`, `verify`, `ship`, `paused` ### `session` — 会话结束总结 ``` projectsmd session # Interactive wizard projectsmd session --non-interactive \ --summary "Implemented auth and wrote tests" ``` 交互式向导: 1. 显示已完成的任务,要求你确认 2. 询问是否做出了任何决策 3. 提示输入会话摘要 4. 更新内容:当前状态、会话日志、任务复选框、前置元数据日期 **标志:** - `--non-interactive` — 跳过提示,使用提供的值 - `--summary TEXT` — 会话摘要(在非交互模式下必需) ### `diff` — 显示自上次会话以来的更改 ``` projectsmd diff ``` 显示自上次会话以来 `project.md` 文件中发生的更改: - 任务状态变化(已完成、被阻塞、新增) - 当前状态变化 - 新决策 - 新会话日志条目 使用 `similar` crate 进行文本差异比较。如果不在 git 仓库中,则与 `.project.md.snapshot` 文件比较。 ### `archive` — 标记项目完成 ``` projectsmd archive # Interactive projectsmd archive --summary "v1.0 released, all features complete" ``` 将状态设置为 `archived`,添加最后的会话日志条目,并更新前置元数据日期。 ### `view` — 将 project.md 渲染到终端 ``` projectsmd view # Full document, syntax-highlighted projectsmd view --section "Tasks" # Just the Tasks section projectsmd view --section "Key Decisions" # Just Key Decisions projectsmd view --section "Current State" # Just Current State ``` 带颜色渲染:绿色表示已完成任务,红色表示被阻塞,灰色表示待处理,决策结果使用彩色显示。 ### `skill` — 管理智能体技能 ``` # 安装代理技能 projectsmd skill install # Auto-detect framework projectsmd skill install --framework claude # For Claude Code projectsmd skill install --framework cursor # For Cursor projectsmd skill install --framework codex # For Codex projectsmd skill install --framework hermes # For Hermes projectsmd skill install --path /custom/path # Custom location projectsmd skill install --force # Overwrite existing # 查看嵌入的技能 projectsmd skill view # 生成项目特定的技能 projectsmd skill generate ``` 详见[智能体集成](#agent-integration)。 ### 全局选项 ``` -f, --file Path to project.md file [default: project.md] --json Output in JSON format (where supported) -q, --quiet Suppress output (only exit code) -h, --help Print help -V, --version Print version ``` ## project.md 文件格式 `project.md` 是一个带有 YAML 前置元数据的结构化 markdown 文件。以下是完整结构: ``` --- project: "My Web App" status: build created: 2026-04-25 updated: 2026-04-29 owner: "Alice" agent: "Claude" tags: [web, typescript, react] repository: "https://github.com/alice/my-web-app" priority: medium --- ## 这是什么 A web application for managing personal book collections. Users can add, rate, and review books. Built with React and TypeScript for a team of three developers. ## 核心价值 Fast, intuitive book management — add a book in under 10 seconds. ## 要求 ### 已验证 - ✓ User authentication with email/password — v0.1 - ✓ Book list with search and filter — v0.1 ### 活跃 - [ ] Book form with title, author, rating fields - [ ] Rating and review system (1-5 stars + text) - [ ] Local storage persistence - [ ] Responsive design for mobile ### 超出范围 - Social features (sharing, following) — adds complexity, different use case - Cloud sync — requires backend, defer to v2 - Import from Goodreads — API rate limits, maintenance burden ## 上下文 - Team of 3 developers, all comfortable with React - Previous version used Angular — migrating to React - Users complained about slow page loads in v1 - Mobile usage is 40% of traffic ## 约束 - **Tech Stack**: TypeScript + React — team expertise, code reuse - **Performance**: Page load under 2 seconds — user retention data - **Compatibility**: Chrome, Firefox, Safari, Edge (last 2 versions) - **Storage**: Local storage only — no backend budget yet ## 当前状态 **Phase:** build **Last completed:** Task 2 (Book list component) **In progress:** Task 3 (Book form with validation) **Next action:** Implement form with React Hook Form + Zod validation **Blockers:** None **Notes:** Chose Zustand for state management during Task 2. ## 架构 Frontend-only React app with local storage: - `src/components/` — React components - `src/stores/` — Zustand state stores - `src/types/` — TypeScript type definitions - `src/utils/` — Helper functions ## 关键决策 | Decision | Rationale | Outcome | |----------|-----------|---------| | Use Vite over CRA | Faster dev server, better ESM | ✓ Good | | Zustand over Redux | Simpler API, less boilerplate | — Pending | | React Hook Form + Zod | Type-safe validation, minimal re-renders | — Pending | ## 任务 ### 阶段:DEFINE - [x] Identify target users and use cases - [x] Define success criteria with owner ### 阶段:DESIGN - [x] Choose technology stack - [x] Design component architecture - [x] Define data models (Book, Review) ### 阶段:BUILD - [x] Task 1: Set up React project with Vite - [x] Task 2: Implement book list component - [ ] Task 3: Add book form with validation - [ ] Task 4: Rating and review system - [ ] Task 5: Local storage persistence ### 阶段:VERIFY - [ ] Unit tests for components - [ ] E2E test: add and view book ### 阶段:SHIP - [ ] README with setup instructions - [ ] Deploy to Vercel ## 发现 - React 19 use() hook simplifies data loading significantly - Zustand's persist middleware handles localStorage automatically ## 参考 - [React Hook Form docs](https://react-hook-form.com/) - [Zustand docs](https://zustand-demo.pmnd.rs/) ## 会话日志 - **2026-04-25** — Project kickoff. Defined requirements, chose stack. (1 hour) - **2026-04-27** — Set up Vite project. Implemented book list. (2 hours) - **2026-04-29** — Started book form. Chose Zustand. (1 hour, ongoing) --- *Last updated: 2026-04-29 after completing Task 2* ``` ### 章节参考 | 章节 | 是否必需 | 用途 | |---------|----------|---------| | **YAML 前置元数据** | 是 | 项目元数据(名称、状态、日期、所有者) | | **这是什么** | 是 | 动态描述 —— 当实际情况发生变化时更新 | | **核心价值** | 是 | 最重要的那一件事 | | **需求** | 是 | 三级生命周期:已验证 / 进行中 / 范围外 | | **上下文** | 推荐 | 背景、环境、先前工作 | | **约束条件** | 推荐 | 硬性限制及其理由 | | **当前状态** | 是 | 关键的续接点 —— 阶段、下一步行动、阻塞项 | | **架构** | 推荐 | 技术方案、文件结构 | | **关键决策** | 是 | 带结果跟踪的决策日志 | | **任务** | 是 | 按阶段分组的任务清单 | | **发现** | 推荐 | 陷阱、变通方法、意外情况 | | **参考文献** | 可选 | 外部链接 | | **会话日志** | 推荐 | 仅追加的时间线 | ### 需求生命周期 需求经历三个层级: ``` [Active] ──shipped──> [Validated] (promoted after proving valuable) │ └──invalidated──> [Out of Scope] (moved with reasoning) ``` - **已验证** — 已发布并被证明有效。已锁定。更改需要讨论。 - **进行中** — 当前范围。在验证前是假设。 - **范围外** — 明确的边界。总是包含理由。 ### 决策结果 跟踪决策是否被证明正确: - ✓ **良好** — 决策被证明正确 - ⚠️ **需重新审视** — 可能需要重新考虑 - — **待定** — 评估为时过早 ## 智能体集成 ### 符合 agentskills.io 规范 `projectsmd` 内置了一个遵循[智能体技能](https://agentskills.io)开放标准的智能体技能。它可以与任何兼容技能的智能体协同工作。 ### 安装技能 ``` # 自动检测您的代理框架 projectsmd skill install # 或显式指定 projectsmd skill install --framework claude # ~/.claude/skills/projectsmd/ projectsmd skill install --framework cursor # ~/.cursor/skills/projectsmd/ projectsmd skill install --framework codex # ~/.codex/skills/projectsmd/ projectsmd skill install --framework hermes # ~/.hermes/skills/projectsmd/ # 自定义路径 projectsmd skill install --path /your/custom/skills/projectsmd/ ``` ### 智能体如何使用它 该技能教授智能体完整的 `project.md` 生命周期: 1. **会话开始:** `projectsmd status` → `projectsmd next` → 阅读当前状态 2. **工作过程中:** `projectsmd task done N`, `projectsmd decide`, `projectsmd discover` 3. **会话结束:** `projectsmd session`(交互式总结) 4. **阶段过渡:** `projectsmd phase transition verify` ### 生成项目特定技能 ``` projectsmd skill generate ``` 创建一个为你的项目量身定制的技能 —— 包含项目名称、当前阶段、任务列表和约束条件。任何获得此技能的智能体都能获得完整上下文。 ### 渐进式披露 技能使用三级加载: 1. **发现** — 智能体读取名称和描述(知道何时使用它) 2. **激活** — 智能体读取完整的 SKILL.md(获取指令) 3. **执行** — 智能体运行 `projectsmd` 命令(执行工作) ### 支持的框架 | 框架 | 安装命令 | 技能位置 | |-----------|----------------|----------------| | Claude Code | `--framework claude` | `~/.claude/skills/projectsmd/` | | Cursor | `--framework cursor` | `~/.cursor/skills/projectsmd/` | | Codex | `--framework codex` | `~/.codex/skills/projectsmd/` | | Hermes | `--framework hermes` | `~/.hermes/skills/projectsmd/` | | 自定义 | `--path /dir/` | `/dir/projectsmd/` | ## 工作流 ### 日常开发 ``` # 一天开始 projectsmd status # Where am I? projectsmd next # What's next? # ……进行工作…… # 一天结束 projectsmd task done 3 # Mark completed tasks projectsmd session # Wrap up ``` ### 多智能体协作 当多个智能体在同一项目上工作时: ``` # 代理 A 开始一个会话 projectsmd task block 3 --reason "Agent B working on API client" # ……处理其他任务…… projectsmd session # 代理 B 接手 projectsmd status # Sees blocked task projectsmd task unblock 3 # ……处理 API 客户端…… projectsmd task done 3 projectsmd session ``` ### 阶段过渡 ``` # 所有 BUILD 任务都完成了吗? projectsmd task list --phase BUILD --pending # Verify none left projectsmd phase transition verify # Move to VERIFY # 所有 VERIFY 任务都完成了吗? projectsmd phase transition ship # Move to SHIP # 项目完成了吗? projectsmd archive --summary "v1.0 released" ``` ### 现有项目 对于现有代码库: ``` projectsmd init --brownfield # 向导从现有代码推断出已验证的要求 # 然后询问您接下来想构建什么(活跃要求) ``` ## 配置 `projectsmd` 不存储任何配置文件。所有状态都保存在 `project.md` 中。 ### 自定义文件位置 ``` projectsmd --file path/to/my-project.md status projectsmd -f ~/projects/weather/project.md validate ``` ### JSON 输出 ``` projectsmd status --json projectsmd validate --json projectsmd task list --json ``` 可用于通过管道传递给 `jq` 或与其他工具集成: ``` projectsmd status --json | jq '.phase' projectsmd task list --json | jq '.tasks[] | select(.status == "pending")' ``` ## 故障排除 ### "未找到 project.md" ``` # 检查您是否在正确的目录中 ls project.md # 或指定路径 projectsmd --file /path/to/project.md status ``` ### "无效的前置元数据" 你的 YAML 前置元数据存在语法错误。常见问题: ``` # 错误 — 缺少围绕含特殊字符的值的引号 project: My App: The Sequel # 正确 project: "My App: The Sequel" ``` ### "未找到章节" 解析器需要精确的标题文本。请确保你的章节匹配: ``` ## 这是什么 # ✓ 正确 ## 这是什么 # ✗ 错误(大小写很重要) ## 摘要 # ✗ 错误(旧格式) ``` ### 验证警告与错误 - **错误** — 必须修复才能符合规范(缺少必需章节、状态无效) - **警告** — 应该修复但不阻塞(缺少推荐章节、日期格式) 运行 `projectsmd validate --strict` 将警告视为错误。 ## 设计决策 ### 单个文件,而非目录 上下文碎片化是问题所在。一个文件迫使保持规范,并使恢复变得简单 —— 只需读取一个文件。 ### 三级需求生命周期 不仅仅是"完成/未完成"。需求在发布和验证前都是假设。三个层级(已验证 / 进行中 / 范围外)可以防止范围悄然蔓延,并创建一个关于什么已被证明的清晰记录。 ### 核心价值作为章节 最重要的一件事。如果其他一切都失败了,这一点必须有效。当需要权衡取舍时,一句话来驱动优先级排序。如果你不能用一句话写出来,那么这个项目还没有被很好地定义。 ### 带结果跟踪的关键决策 不仅仅是"决定了什么",还有"它是否有效?"。会话之间丢失的首要上下文是决策的*原因*以及它是否被证明是正确的。 ### 当前状态作为续接点 一个只读当前状态章节的智能体就知道下一步该做什么。每次会话都更新 —— 这是不可协商的。 ### 演化规则 文档是动态的,而非静态的。章节在阶段过渡和里程碑时更新。"这是什么"在现实情况发生变化时更新。需求被提升或淘汰。 ## 受启发于 - **[obra/superpowers](https://github.com/obra/superpowers)** — 智能体技能流程(头脑风暴 → 规划 → 执行),验证先于完成的理念,子智能体驱动的开发 - **[Get Shit Done (GSD)](https://github.com/gsd-build/get-shit-done)** — PROJECT.md 模板,需求生命周期(已验证/进行中/范围外),决策结果跟踪,演化规则,现有项目支持 - **[智能体技能](https://agentskills.io)** — 智能体技能打包和渐进式披露的开放标准 - **敏捷/Scrum** — Sprint 结构,回顾会议,增量交付 - **Shape Up** — 基于意愿范围界定,断路器机制,塑造先于构建 ## 许可证 MIT — 详见 [LICENSE](LICENSE)。
标签:AI代理, Linux 内核安全, Markdown, Rust, 上下文保持, 上下文管理, 人工智能辅助, 任务管理, 协作工具, 单文件存储, 可视化界面, 命令行界面, 执行监控, 文档结构分析, 无Web服务, 无数据库, 网络流量审计, 软件开发, 轻量级工具, 通知系统, 防御加固, 项目管理, 项目管理软件, 项目范围, 项目跟踪