Skip to content

AGENTS.md

Latest commit

 

History

History
97 lines (77 loc) · 4.56 KB

AGENTS.md

File metadata and controls

97 lines (77 loc) · 4.56 KB
Raw

AGENTS.md

项目说明

xushi 是 AI agent 优先的本地化日程管理与调度底座。项目级规则继承用户级 AGENTS.md；若本文件与用户级规则冲突，以更贴近当前仓库的项目级规则为准。

技术栈

  • Python 3.12+，依赖和运行命令使用 uv。
  • FastAPI 提供本地 HTTP API，Typer 提供 CLI。
  • SQLite 保存任务、运行记录、投递记录和通知记录；executor 配置保存在本地 config.json，不写入数据库。
  • Pydantic 定义任务、调度、运行记录、投递和 executor schema。
  • OpenClaw 插件使用 TypeScript/ESM，运行时入口为 plugins/openclaw-xushi/dist/index.js。
  • PyInstaller 用于构建跨平台 xushi 和 xushi-daemon 二进制。

常用命令

uv sync
uv run pytest
uv run ruff check .
uv run python scripts/check_project_metadata.py
node --check plugins/openclaw-xushi/dist/index.js
uv build --wheel

本地开发启动：

uv run xushi init --show-token
uv run xushi-daemon

模块边界

  • src/xushi/models.py：对外任务、调度、运行、投递、executor 契约。
  • src/xushi/scheduler.py：只计算到期事实、错过补偿和跟进时间。
  • src/xushi/service.py：组合调度、存储、投递、确认、跟进、聚合和重试流程。
  • src/xushi/storage.py：SQLite schema、迁移、索引和持久化查询。
  • src/xushi/delivery.py：免打扰和提醒摘要等投递层策略。
  • src/xushi/executors.py：OpenClaw、Hermes 和预留 webhook executor 调用。
  • src/xushi/api.py、src/xushi/cli.py、src/xushi/capabilities.py：HTTP、CLI 和 agent 能力发现入口。
  • plugins/openclaw-xushi：OpenClaw 插件源码和运行时构建产物。
  • skills/xushi-skills：面向 OpenClaw/Hermes agent 的序时任务类型指南。
  • src/xushi/bundled_plugins 与 src/xushi/bundled_skills：随应用打包的内置副本。

文档同步

  • docs/superpowers/README.md 是文档入口；后续需求、架构、接口、数据模型、 安装发布、agent 集成和流程设计都以 docs/superpowers/ 下的文档为准。
  • docs/PROJECT_REQUIREMENTS.md 和 docs/TECHNICAL_DESIGN.md 已迁移并移出工作树； 后续不要重新创建或把它们当作事实源。需要追溯时读取 git history。
  • 项目基线事实写在 docs/superpowers/specs/2026-05-25-*-design.md。
  • 新需求或设计变更继续新增 Superpowers spec；实施计划写入 docs/superpowers/plans/。
  • 需求或设计不清楚时，先读 docs/superpowers/README.md 和相关 Superpowers spec； 仍不明确再向用户确认，确认后再改文档和代码。

验证要求

  • Python 行为变更优先补测试，再实现。
  • 修改调度、投递、确认、SQLite schema、API、CLI 或 executor 行为时，至少运行相关 targeted tests，并在完成前运行 uv run pytest。
  • 修改样式、导入、文档中受 lint 约束的代码示例或 Python 代码时，运行 uv run ruff check .。
  • 修改版本号、OpenClaw 插件、内置 plugin/skills 副本、发布脚本或 README 分发信息时， 运行 uv run python scripts/check_project_metadata.py。
  • 修改 OpenClaw 插件运行时后，确保 plugins/openclaw-xushi/dist/index.js 与源码意图一致， 并运行 node --check plugins/openclaw-xushi/dist/index.js。

插件和内置资源

  • plugins/openclaw-xushi 是插件源码目录； src/xushi/bundled_plugins/openclaw-xushi 是应用内置安装副本，二者需要保持一致。
  • skills/xushi-skills 是 skills 源码目录； src/xushi/bundled_skills/xushi-skills 是应用内置安装副本，二者需要保持一致。
  • OpenClaw 插件复制式安装不执行 npm install；插件运行入口不得新增普通 npm 运行时依赖，除非同时调整安装和打包设计。

安全边界

  • 不要提交 ~/.xushi/config.json、SQLite 用户数据、token、hook 密钥或真实账号信息。
  • XUSHI_API_TOKEN 用于 agent/plugin 调用 xushi-daemon； OPENCLAW_HOOKS_TOKEN 和 HERMES_API_TOKEN 用于 xushi-daemon 调用外部 agent hook， 不要混淆方向。
  • 默认保持 daemon 只监听 127.0.0.1。若要暴露到局域网或外部系统，必须先确认安全影响。
  • 涉及真实用户通知、真实 agent hook、真实聊天渠道或外部写操作时，先确认影响范围。

交付要求

  • 保持改动聚焦，不做无关重构。
  • 完成后说明改动内容、验证命令和仍未验证的风险。
  • 遇到用户已有改动时，保留并顺着现有改动工作，不要擅自回滚。