Knowns CLI

Knowns CLI：让 AI 真正理解你的项目 ✨

Knowns CLI 是一款以 AI 为核心的命令行工具，专为任务管理和文档记录打造。它旨在终结项目中上下文丢失的烦恼，让您和您的 AI 助手始终同步，专注于创造而非琐碎的管理。

💡 核心价值：告别手动粘贴和重复提示。当你说“处理任务 42”时，AI 能自动读取任务状态、检查相关文档，并确切知道“完成”意味着什么。

---

🎯 为什么选择 Knowns？

现代开发常常需要在任务、文档和多个工具间不停切换，上下文极易丢失。Knowns 将一切统一起来：

• 为 AI 而生：自动为 AI 助手加载项目上下文，通过 @doc/... 或 @task-... 无缝引用。
• CLI 优先：一切操作都在终端完成，高效直接。
• Git 友好：所有数据以 Markdown 形式存储在 .knowns/ 目录中，纯文本，零锁定。
• 闭环学习：AI 解决问题后，可自动提取知识并更新项目文档，让团队智慧持续沉淀。

---

🧩 核心概念一览

了解几个简单概念，即可开始使用：

• 任务 (Tasks)：每个任务包含标题、描述、验收标准和状态（如待办、进行中、完成）。
• 文档 (Documentation)：存放在 .knowns/docs/ 的 Markdown 文件，可在任务中被引用。
• 时间追踪 (Time Tracking)：内置计时器，帮助您记录在任务上花费的时间。

---

🤖 AI 工作流指南

为 AI 助手（如 Claude、GPT）设计了清晰的工作协议，确保协作顺畅：

1. 始终使用 CLI：禁止直接编辑 .md 文件，所有修改都通过 knowns 命令进行。
2. 文档优先：编码前，务必通过 knowns doc view --smart 阅读所有相关文档。
3. 使用明文输出：为 AI 执行命令时，总是加上 --plain 标志以获取机器可读的结果。
4. 遵循检查清单：在写代码前，确认已理解项目架构、编码约定并识别了可复用模式。

✨ Knowns 提供模块化指南，AI 可在会话开始时通过 knowns agents guideline 获取，确保行为一致。

---

⚙️ 主要命令速览

以下是一些最常用的命令，帮助您快速上手：

• knowns task create – 创建新任务。
• knowns task list – 列出所有任务（支持状态、优先级等过滤）。
• knowns doc view <path> --smart – 查看文档（智能处理大小文档）。
• knowns time start/stop – 开始/停止任务计时。
• knowns search – 跨任务和文档搜索。
• knowns init – 在当前目录初始化 Knowns（交互式向导）。

---

🔗 无缝集成：Claude Desktop (MCP)

通过 Model Context Protocol (MCP)，Knowns 可与 Claude Desktop 深度集成。

一键设置：运行 knowns mcp setup，工具会自动创建配置文件并注册服务器，重启 Claude Code 后即可直接访问您的任务和文档上下文。

---

📦 开始使用

Knowns 需要 Node.js 18+ 或 Bun 1.0+ 环境。只需几步即可融入您的工作流：

1. 安装后，在项目根目录运行 knowns init 进行初始化。
2. 使用 knowns task create 创建您的第一个任务。
3. 在任务描述中引用文档，例如“请参考 @doc/architecture/api”。
4. 让 AI 助手接管时，它便能基于完整的上下文为您智能工作。

所有数据都属于您，存储在清晰的结构中，随时可读、可编辑。