Project OS Organizer

Project OS Organizer 技能

为何需要此技能

当用户同时处理多个由 AI 构建的项目，且需要一个简洁统一的命令入口时，请使用本技能，以实现以下目标：

1. 快速查看当前活跃的项目；
2. 高效记录项目进展与下一步动作；
3. 一键恢复任意项目（本地 / GitHub / 聊天会话）。

安全默认设置

1. 远程安装默认禁用；
2. 聊天记录索引默认禁用；
3. GitHub 同步/令牌使用默认禁用；
4. 主目录启发式发现默认禁用。

如需显式启用以下功能，请设置对应环境变量：

1. PROJECT_OS_INCLUDE_CHAT_ROOTS=1：启用聊天记录索引；
2. PROJECT_OS_ENABLE_GITHUB_SYNC=1：启用 GitHub 用户名/令牌集成；
3. PROJECT_OS_ENABLE_HOME_DISCOVERY=1：启用广泛的主目录发现；
4. PROJECT_OS_AUTO_SETUP=1 PROJECT_OS_ALLOW_REMOTE_INSTALL=1：当 PROJECT_OS_ROOT 缺失时，允许远程克隆/安装。

目标

构建一份完整、以本地为优先的项目清单，准确回答以下问题：

1. 当前存在哪些项目？
2. 哪些项目处于活跃 / 阻塞 / 沉寂状态？
3. 每个项目实际是关于什么的？
4. 用户上次操作停留在何处？
5. 用户如何立即重新进入该项目？
6. 用户如何在不离开 OpenClaw 的前提下，快速编辑项目状态、下一步动作或待办事项？

默认行为（自然语言优先）

对每条用户消息执行以下默认动作：

1. 解析用户输入；
2. 执行：scripts/project_router.sh ""；
3. 直接以纯文本形式返回路由器输出。

用户无需手动输入脚本、Python 命令、路径或参数标志。

高级用户备用方式：

• 使用简短封装命令：project ...；
• 示例：project、project focus、project today、project inbox "idea: test"、project dashboard start。

自然语言请求映射关系：

1. “我今天在忙什么？” → 活动日报（今日）；
2. “显示我的项目” → 分组项目列表（Now / Later / Blocked / Done）；
3. “焦点列表” → 顶部聚焦事项；
4. “添加这个想法：……” → 收入收件箱（inbox）；
5. “project-os 的下一步是……” → 添加下一步动作；
6. “将 X 标记为阻塞” → 设置简易状态；
7. “启动仪表板” → 启动 dashboard；
8. “恢复项目 X” → 恢复打包（resume pack）；
9. “仅追踪 A、B、C” → 设置追踪范围（后续活动仅包含这些项目）；
10. “静音 X” / “取消追踪 X” / “显示当前范围” → 范围控制指令。

非技术模式下的响应风格：

1. 响应应简短直接；
2. 除非用户主动询问，否则不暴露底层技术命令细节；
3. 对于活动类问题，始终返回 Activity Criteria 及按日划分的章节（如 Today / Yesterday）；
4. 若项目名称存在歧义，仅提出一个简短澄清问题。

项目定义

满足以下任一条件的条目即视为一个项目：

1. Git 仓库文件夹；
2. 非 Git 代码文件夹，但包含项目标识文件（如 package.json、pyproject.toml、Cargo.toml 等）；
3. 聊天会话（Claude / Codex），且该会话未匹配到已有项目；此时创建一个由聊天派生的项目；
4. Claude workspace 类型的聊天会话，若其会话文件夹路径表明嵌套 workspace 结构，则应映射至更深层的子项目。

排除规则（在采集根目录中）：

• 明显非项目类文件夹（如仅含文档、日志、备份、纯笔记的文件夹），除非有强代码证据或项目标记；
• 低信噪比的纯聊天条目，不应作为独立项目，除非其中包含有效路径提示或明确的项目意图。

必需工作流

1. 首先运行：scripts/bootstrap.sh；

2. 验证覆盖范围：

   • python3 -m project_os.cli --db ~/.project_os/openclaw_test.db --config ~/.project_os/openclaw_test_config.json list-projects --limit 200；
   • python3 -m project_os.cli --db ~/.project_os/openclaw_test.db --config ~/.project_os/openclaw_test_config.json list-sessions --limit 50；
   • python3 -m project_os.cli --db ~/.project_os/openclaw_test.db --config ~/.project_os/openclaw_test_config.json list-items --status open --limit 80；
   • python3 -m project_os.cli --db ~/.project_os/openclaw_test.db --config ~/.project_os/openclaw_test_config.json squash-chat-projects；
3. 若用户需要可视化界面，运行：scripts/start_dashboard.sh；
4. 若用户需要快速恢复上下文，运行：scripts/write_memory.sh，并查阅 ~/.project_os/PROJECT_MEMORY.md。

首次运行（生产环境）

首次使用用户请执行以下步骤：

1. scripts/openclaw_smoke_agent.sh；
2. scripts/read_smoke_result.sh；

3. 确认以下三项输出：

   • RESULT_STATUS=ok；
   • RESULT_DASHBOARD_URL=...；
   • RESULT_PORT_8765_LISTENING=yes。

若本地不存在 project-os 仓库，本技能将默认安全失败，并提示用户设置 PROJECT_OS_ROOT。远程安装仅在显式启用后才生效。

运行模式

• 仪表板模式（Dashboard mode）：提供简洁的可视化分类视图（Focus Today、Now、Blocked、Later、Done）及跳转链接；

• 仪表板模式包含以下能力：

  • 快速收件箱捕获（自由格式笔记 → 自动路由为更新 / 下一步 / 提醒 / 想法 / 阻塞项）；
  • 每日签到面板（已完成 + 下一步 + 阻塞项）；
  • 聚焦列表、沉寂提醒、周度快照、服务健康状态；

• 仪表板设计原则：刻意避免推荐评分等噪声干扰，专注自然语言表达：

  • 项目是什么（从 README 或 package 元数据等文件中推导）；
  • 上次停在哪；
  • 接下来做什么；
  • 内联编辑支持：设置简易状态（now / later / blocked / done）、设置下一步动作、添加更新 / 下一步 / 提醒 / 想法 / 阻塞项、标记事项为完成 / 已忽略；
  • 当会话链接有效时，提供双工具恢复按钮（Resume in Claude 和 Resume in Codex）；
• 记忆模式（Memory mode）：生成 Markdown 快照，便于在任意聊天环境中快速恢复上下文。

默认建议：两种模式配合使用。

OpenClaw 命令优先更新方式

CLI 命令作为主要交互接口：

1. add-update：记录已发生变更；
2. add-next：指定紧接下一步（同步更新项目 next_action 字段）；
3. add-reminder：添加带日期/时间的后续提醒；
4. add-idea：存入待评估的想法；
5. list-items 与 set-item-status：用于事项分类与关闭；
6. 可通过 scripts/project_actions.sh 调用上述命令的简短别名；

7. 对于“我今天/昨天做了什么？”类活动窗口问题，运行：

   • scripts/activity_report.sh --when both 或
   • scripts/project_actions.sh activity --when both；
8. 严禁仅凭项目名或状态猜测活动内容；必须严格依据报告判定标准中的时间戳证据；
9. 活动报告默认排除已归档项目（仅当用户明确要求时，才可加 --include-archived）；

10. 活动窗口类响应契约：

    • 必须包含 Activity Criteria；
    • 必须包含 Today (...) 和/或 Yesterday (...) 标题；
    • 每个列出的项目至少提供一条证据行（local_commit、github_push、session 或 note）；
    • 若无匹配项目，必须明确返回 - none。

OpenClaw 使用方式

1. 在 OpenClaw 中，通过技能名称调用：project-os-organizer；
2. 首次运行配置：project setup（或 scripts/easy_mode.sh setup）；
3. 日常使用：直接在聊天中输入自然语言，由 project_router.sh 自动路由；
4. 可选快捷方式：仅需输入 project ...；
5. 从本仓库一键本地安装：scripts/install_openclaw_skill.sh；

6. 面向非交互式 OpenClaw Agent 的专用命令：

   • scripts/openclaw_smoke.sh：严格 CI 风格冒烟测试（失败时返回非零退出码）；
   • scripts/openclaw_smoke_agent.sh：Agent 安全型冒烟测试（恒返回零退出码，结果通过 RESULT_STATUS 输出）；
   • scripts/read_smoke_result.sh：在命令输出不稳定时，读取最近一次冒烟测试的结果文件；
   • scripts/bootstrap.sh --noninteractive：超时安全的快速初始化模式；
   • scripts/bootstrap.sh --noninteractive-full：全量刷新模式；
   • scripts/start_dashboard.sh --detach --restart：后台启动并自动重启 dashboard；

   • 所有冒烟命令均输出机器可读字段：

     • RESULT_STATUS
     • RESULT_ERROR
     • RESULT_DASHBOARD_URL
     • RESULT_DASHBOARD_PID
     • RESULT_PORT_8765_LISTENING
     • RESULT_CURL_HEAD
     • RESULT_SMOKE_LOG
     • RESULT_DASHBOARD_LOG
     • RESULT_RESULT_FILE

7. 从聊天中快速编辑项目信息：

   • scripts/project_actions.sh list --limit 80
   • scripts/project_actions.sh set-status --project "" --status blocked|id>
   • scripts/project_actions.sh set-next --project "" --text "next step"|id>
   • scripts/project_actions.sh add-update --project "" --text "what changed"|id>
   • scripts/project_actions.sh add-next --project "" --text "immediate next step"|id>
   • scripts/project_actions.sh add-reminder --project "" --text "follow up" --due 2026-03-01|id>
   • scripts/project_actions.sh add-blocker --project "" --text "what is blocked"|id>
   • scripts/project_actions.sh simple-status --project "" --status now|id>
   • scripts/project_actions.sh focus --limit 3
   • scripts/project_actions.sh stale --days 14 --limit 20
   • scripts/project_actions.sh weekly --days 7 --limit 12
   • scripts/project_actions.sh notify --period daily
   • scripts/project_actions.sh inbox --text "freeform note"
   • scripts/project_actions.sh checkin --project "" --done "..." --next "..." --blocker "..."|id>
   • scripts/project_actions.sh duplicates --limit 50
   • scripts/project_actions.sh merge --keep "" --drop ""|name>|name>
   • scripts/project_actions.sh ask --text "mark project-os blocked"
   • scripts/project_actions.sh set-item --item--status done

8. 查询“今天/昨天做了什么”：

   • scripts/project_actions.sh activity --when both

9. 个人范围控制：

   • scripts/project_actions.sh scope --set "project-os" "polymarket-trader-v2"
   • scripts/project_actions.sh track --project "project-os"
   • scripts/project_actions.sh mute --project "clawd"
   • scripts/project_actions.sh scope
   • --include-archived 仅在用户明确要求时添加；
   • 返回输出必须包含 Activity Criteria、Today (...) 和 Yesterday (...) 三部分，确保用户清晰了解项目统计逻辑。

安全性与作用域约束

1. 严格以本地为优先，不依赖远程服务作为前提；
2. 不自动修改任何仓库或服务器；
3. 不虚构项目状态；所有推断必须基于扫描结果或会话数据，并主动暴露不确定性；
4. 优先保障根目录级广泛覆盖，避免遗漏嵌套子文件夹；
5. 默认关闭非 Git 项目的嵌套发现（include_nested_non_git_projects: false），防止 submodule 等噪声干扰；
6. 采集发现策略保持严格：仅纳入真实项目子目录，剔除随机纯文本文件夹。

参考资料

• references/project-definition.md
• references/workflow.md

命令行