内容
<p align="center">
<img src="./Owlyn.png" alt="Owlyn MCP logo" width="760" />
</p>
# Owlyn MCP
Owlyn MCP 是一个为 AI 编程代理设计的本地优先的 MCP 工作会话监督工具，它们需要截止日期、检查点和结构化的继续决策，而不是一个简单的计时器。
<p align="center">
<a href="https://github.com/btitkin/OwlynMCP/actions/workflows/ci.yml"><img src="https://github.com/btitkin/OwlynMCP/actions/workflows/ci.yml/badge.svg" alt="CI" /></a>
<a href="https://github.com/btitkin/OwlynMCP/releases"><img src="https://img.shields.io/github/v/release/btitkin/OwlynMCP?include_prereleases&label=release" alt="GitHub release" /></a>
<a href="./LICENSE"><img src="https://img.shields.io/github/license/btitkin/OwlynMCP" alt="License" /></a>
<img src="https://img.shields.io/badge/node-%3E%3D20-339933" alt="Node.js 20+" />
</p>
它适用于使用代理编码工具的开发人员，他们希望长时间运行的工作会话保持明确、可检查并受安全规则约束。
AI 代理通常过早停止。你要求代理工作到 06:00，它在 20 分钟内完成第一个任务，然后说“完成”。Owlyn 旨在使继续决策明确化。
## 预览
截图/GIF 演示即将推出。
存储库包括上面的 Owlyn 徽标和 [docs/EXAMPLE_SESSION.md](./docs/EXAMPLE_SESSION.md) 中的示例会话文档。
## 功能
- 使用官方 MCP SDK 构建的标准输入输出 MCP 服务器。
- 通过 `better-sqlite3` 进行本地 SQLite 会话存储。
- 工作会话生命周期工具：启动、状态、检查点、是否继续、计划下一个、结束、列出会话和报告。
- 具有时间感知工作会话的截止日期和时区处理。
- 保守的继续策略，在高风险、破坏性或需要审批的工作中停止。
- 用于将 Owlyn 集成到编码代理工作流中的主机设置和代理指令文档。
- 锻炼核心工具流的 MCP 烟雾测试。
## 安装
要求：
- Node.js 20+
- npm
```bash
git clone https://github.com/btitkin/OwlynMCP.git
cd OwlynMCP
npm install
npm run build
```
安装说明基于当前的存储库结构，应针对每个 MCP 主机进行验证。
## 快速开始
运行标准输入输出 MCP 服务器：
```bash
node dist/index.js
```
通用 MCP 服务器配置：
```json
{
"mcpServers": {
"owlyn": {
"command": "node",
"args": ["/absolute/path/to/OwlynMCP/dist/index.js"],
"env": {
"OWLYN_DB_PATH": "/absolute/path/to/.owlyn/owlyn.sqlite"
}
}
}
}
```
更多主机设置说明在 [docs/HOST_SETUP.md](./docs/HOST_SETUP.md) 中。
## 示例/用例
- 启动具有目标和截止日期的有界 AI 代理工作会话。
- 保存包括已完成工作、下一个任务、验证和阻塞器的检查点。
- 在当前任务完成后询问代理是否应继续。
- 在会话中剩余时间时，排名安全下一个任务。
- 在结束工作之前生成会话报告。
## 路线图
参见 [docs/ROADMAP.md](./docs/ROADMAP.md)，了解从 alpha 到 v1.0 的发布路径。
v1.0 之后的未来想法包括可选的 JSON/Markdown 导出、会话模板、主机特定的配置助手、每个项目的会话配置文件以及可选的暂停/恢复控件。
这些项目在当前的 alpha 版本中尚未实现。
## 状态
Alpha：当前的公共版本是 `v0.1.0-alpha.2`，包括测试、文档、GitHub Actions CI 和手动 MCP 烟雾测试，并在 Windows 上的 Codex MCP 主机上经过验证。更广泛的主机兼容性仍应被视为待定，除非在目标主机上验证。
## Codex-first 状态
Owlyn MCP 目前在 Windows 上的 Codex MCP 主机上经过验证。
扩展的 Codex 验证场景通过了继续决策、安全门、专注模式、马拉松模式、截止日期处理、任务排名、报告、结束、重启/重新加载行为以及持久配置的 `OWLYN_DB_PATH` 行为。干净的临时数据库路径验证仍然是可选/待定的，除非单独测试。
下一个重点是更深入的 Codex 工作流验证：
- 长运行工作会话
- 继续决策
- 检查点质量
- 干净的临时数据库路径验证
- 安全的下一个任务规划
其他 MCP 主机仍然待定。
Codex 文档：
- [Codex MCP 设置](./docs/CODEX_MCP_SETUP.md)
- [Codex 代理说明](./docs/CODEX_AGENT_INSTRUCTIONS.md)
- [Codex 验证场景](./docs/CODEX_VALIDATION_SCENARIOS.md)
- [Codex 验证日志](./docs/CODEX_VALIDATION_LOG.md)
## 通用主机验证状态
已验证：
- Windows 上的 Codex MCP 主机
待定：
- Cursor
- Claude Desktop
- 其他 MCP 标准输入输出主机
参见 [实际主机验证](./docs/REAL_HOST_VALIDATION.md)、[主机设置](./docs/HOST_SETUP.md) 和共享的 [验证提示](./docs/VALIDATION_PROMPT.md)。
## 更多文档
- [FAQ](./docs/FAQ.md)
- [主机设置](./docs/HOST_SETUP.md)
- [实际主机验证](./docs/REAL_HOST_VALIDATION.md)
- [Codex MCP 设置](./docs/CODEX_MCP_SETUP.md)
- [Codex 代理说明](./docs/CODEX_AGENT_INSTRUCTIONS.md)
- [Codex 验证场景](./docs/CODEX_VALIDATION_SCENARIOS.md)
- [Codex 验证日志](./docs/CODEX_VALIDATION_LOG.md)
- [验证提示](./docs/VALIDATION_PROMPT.md)
- [npm 发布准备](./docs/NPM_PUBLISHING.md)
- [路线图](./docs/ROADMAP.md)
- [工具参考](./docs/TOOLS.md)
- [代理说明](./docs/AGENT_INSTRUCTIONS.md)
- [社交帖子草稿](./docs/SOCIAL_POST.md)
## 开发
```bash
npm install
npm run typecheck
npm run build
npm test
npm run smoke:mcp
npm run check
```
发布检查清单：[RELEASE_CHECKLIST.md](./RELEASE_CHECKLIST.md)。
## 许可证
MIT。参见 [LICENSE](./LICENSE)。
