Metadata-Version: 2.2
Name: aicorkit
Version: 0.1.3
Summary: AI-powered desktop tool orchestration CLI
Author: eric.zhang
License: Apache-2.0
Project-URL: Homepage, https://gitee.com/seacozz2007/aicorkit
Project-URL: Repository, https://gitee.com/seacozz2007/aicorkit
Project-URL: Issues, https://gitee.com/seacozz2007/aicorkit/issues
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click>=8.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: pywin32>=306; platform_system == "Windows"
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Provides-Extra: meeting
Requires-Dist: sounddevice>=0.4.6; extra == "meeting"
Requires-Dist: numpy>=1.24; extra == "meeting"
Requires-Dist: soundfile>=0.12; extra == "meeting"
Requires-Dist: openai>=1.0; extra == "meeting"
Requires-Dist: dashscope>=1.20; extra == "meeting"
Requires-Dist: pywinauto>=0.6.9; extra == "meeting"
Requires-Dist: pyautogui>=0.9; extra == "meeting"
Provides-Extra: all
Requires-Dist: aicorkit[meeting]; extra == "all"
Requires-Dist: aicorkit[graph]; extra == "all"
Provides-Extra: graph
Requires-Dist: numpy>=1.24; extra == "graph"
Requires-Dist: dashscope>=1.20; extra == "graph"
Requires-Dist: openai>=1.0; extra == "graph"
Requires-Dist: markitdown[docx,pdf,pptx,xls,xlsx]>=0.1.6; extra == "graph"

# aicorkit

面向 AI Agent（Kiro / Claude 等）的 **Windows 桌面自动化 CLI**。通过 pywin32 直接驱动 Outlook COM，并提供本地知识库（Graph / Memory Tree）、会议语音管道等能力。

## 环境要求

- **Python 3.10+**
- **Windows**（Outlook COM、会议音频依赖 Windows 主机）
- Outlook 桌面客户端已安装并登录（使用邮件/日历时）
- 可选：`DASHSCOPE_API_KEY`（会议 STT/TTS、Graph 向量 embedding）

## 安装

### 从源码安装

```powershell
cd D:\CODE\aicorkit
pip install -e .
```

### 可选依赖

| 包 | 用途 | 命令 |
|----|------|------|
| `[graph]` | 知识库向量检索（numpy、dashscope、openai） | `pip install -e ".[graph]"` |
| `[meeting]` | 会议 STT → LLM → TTS 管道 | `pip install -e ".[meeting]"` |
| `[dev]` | 开发测试 | `pip install -e ".[dev]"` |
| `[all]` | graph + meeting | `pip install -e ".[all]"` |

### Windows 运行方式

若 `aicorkit` 不在 PATH，可用模块方式调用（推荐）：

```powershell
python -m aicorkit --help
python -m aicorkit graph status
```

pip 脚本目录常见位置：`%AppData%\Roaming\Python\Python313\Scripts`（可按需加入 PATH）。

## 配置

配置分两层，**项目级覆盖全局**：

| 层级 | 路径 |
|------|------|
| 全局 | `~/.aicorkit/config.yaml` |
| 项目 | `<项目根>/.aicorkit/config.yaml`（从当前目录向上查找最近一份） |

```powershell
python -m aicorkit config init
python -m aicorkit config show
python -m aicorkit config paths
python -m aicorkit config set backend kiro
python -m aicorkit config set graph.embed.provider dashscope
python -m aicorkit config set atlassian.jira_url https://jira.example.com
python -m aicorkit config set atlassian.confluence_url https://wiki.example.com
```

凭据写入 `~/.aicorkit/secrets.env`（勿提交 git）：

```
ATLASSIAN_USERNAME=your_user
ATLASSIAN_PASSWORD=your_password
```

项目级示例（仓库根目录 `.aicorkit/config.yaml`）：

```yaml
graph:
  workspace: .aicorkit/memory    # 项目独立知识库目录

graph_sources:
  - id: repo-docs
    kind: folder
    label: 项目文档
    enabled: true
    path: ./docs
    glob: "**/*.md"
```

列表字段（如 `graph_sources`）会被项目 config **整段替换**，不会与全局逐项合并。

## 使用说明

### Outlook

```powershell
# 只读
python -m aicorkit outlook list-emails -f Inbox -c 10
python -m aicorkit outlook read-email -q "季度报告"
python -m aicorkit outlook list-calendar -d 7
python -m aicorkit outlook shared-calendar --email boss@company.com -d 7
python -m aicorkit outlook free-busy --email colleague@company.com -d 3
python -m aicorkit outlook list-rooms

# 写入（Agent 执行前需用户确认）
python -m aicorkit outlook send-email --to "a@b.com" --subject "Hi" --body "Hello"
python -m aicorkit outlook create-meeting `
  --subject "Sprint Review" `
  --start "2026-06-08 14:00" `
  --duration 60 `
  --attendees "team@company.com"
```

| 命令 | 说明 |
|------|------|
| `outlook list-emails` | 列出收件箱/已发送邮件 |
| `outlook read-email` | 按主题关键词搜索并读取 |
| `outlook send-email` | 发送邮件 |
| `outlook list-calendar` | 查看近期日程 |
| `outlook create-meeting` | 创建会议邀请 |
| `outlook shared-calendar` | 查看他人共享日历 |
| `outlook free-busy` | 查看他人忙闲 |
| `outlook list-rooms` | 常用会议室 |

### Meeting（会议语音）

需 `pip install -e ".[meeting]"` 和 `DASHSCOPE_API_KEY`。会议 LLM 默认使用 **cursor-agent**（`meeting.backend: cursor`），与顶层 `backend` 独立。

```powershell
python -m aicorkit meeting listen          # STT → LLM → TTS
python -m aicorkit meeting auto-answer
python -m aicorkit meeting start           # listen + auto-answer

python -m aicorkit config set meeting.backend cursor   # 默认已是 cursor
python -m aicorkit config set meeting.backend kiro     # 改回 kiro-cli
python -m aicorkit config set meeting.graph_archive true
```

### Jira / Confluence

需配置 `atlassian.jira_url`、`atlassian.confluence_url` 与 `secrets.env` 凭据。

```powershell
# 连接测试
python -m aicorkit atlassian test

# Jira 只读
python -m aicorkit jira search --jql "assignee = currentUser() AND status != Done"
python -m aicorkit jira get-issue CMS-123
python -m aicorkit jira list-boards --project CMS
python -m aicorkit jira list-sprints --board-id 945 --state active

# Confluence 只读
python -m aicorkit confluence search --space AESCESS -q "API"
python -m aicorkit confluence list-pages --space AESCESS
python -m aicorkit confluence get-page --id 13069892

# 写入（需 --yes，Agent 须先征得用户确认）
python -m aicorkit jira add-comment CMS-123 --body "..." --yes
python -m aicorkit jira transition CMS-123 --to "In Progress" --yes
python -m aicorkit confluence update-page --id 123 --version 5 --body "..." --yes
```

| 命令组 | 只读 | 写入（需 `--yes`） |
|--------|------|---------------------|
| `jira` | search, list-issues, get-issue, list-comments, list-projects, list-boards, list-sprints, list-board-issues | create-issue, add-comment, transition, update-issue |
| `confluence` | search, list-spaces, list-pages, get-page | update-page, add-comment |

### Graph 知识库

本地 **SQLite + Obsidian 兼容 wiki/**，支持入库、检索、摘要树、实体图。

**数据位置**

| 项 | 默认路径 |
|----|----------|
| 全局 workspace | `~/.aicorkit/memory/` |
| 项目 workspace | `<项目>/.aicorkit/memory/` |
| 数据库 | `chunks.db` |
| Vault | `wiki/` |
| 精编记忆 | `~/.aicorkit/MEMORY.md`（可配置） |

**一键 setup（推荐）**

```powershell
# 最小：init + notes 源 + INDEX + dashboard
python -m aicorkit graph setup --yes

# 完整：项目 config + 文档 + Outlook + 同步 + skill
python -m aicorkit graph setup --yes --project --docs ./docs --outlook --sync --skill-platform cursor
```

**初始化与状态**

```powershell
python -m aicorkit graph init
python -m aicorkit graph status
```

**入库**（写入操作需 `--yes`）

```powershell
python -m aicorkit graph ingest document `
  --source-id "proj:design" --title "设计" --body-file ./design.md --yes

python -m aicorkit graph ingest file --path ./note.md --source-id "notes:manual" --yes

python -m aicorkit graph ingest email --from outlook --folder Inbox -c 20 --yes

python -m aicorkit graph ingest chat --source-id "chat:s1" --file turns.json --yes
Get-Content turns.json -Raw | python -m aicorkit graph ingest chat --source-id "chat:s1" --stdin --yes

python -m aicorkit graph ingest meeting --file meeting.json --yes
```

**数据源同步**

```powershell
python -m aicorkit graph source list
python -m aicorkit graph source add --kind folder --label "文档" --path D:/docs --yes
python -m aicorkit graph source add --kind outlook --label "收件箱" --folder Inbox --yes
python -m aicorkit graph source sync --all --yes
```

支持 `folder` / `outlook` / `web` / `notes`。

**检索**（只读，Agent 可直接调用）

```powershell
python -m aicorkit graph search "知识库架构"
python -m aicorkit graph search "设计" --mode hybrid -n 10
python -m aicorkit graph search --entity "项目"
python -m aicorkit graph fetch --chunk-ids "chunk_id1,chunk_id2"

python -m aicorkit graph query source --id docs:design -d 7
python -m aicorkit graph query global -d 1
python -m aicorkit graph query topic --entity "知识库"
python -m aicorkit graph drill --node-id <node_id> --depth 2
python -m aicorkit graph walk "上周会议结论" -n 5
```

向量检索需配置 embedding：

```powershell
python -m aicorkit config set graph.embed.provider dashscope   # DASHSCOPE_API_KEY
python -m aicorkit config set graph.embed.provider ollama       # 本地 Ollama
python -m aicorkit config set graph.embed.provider openai        # OpenAI-compatible
```

**Worker 与摘要树**

入库后异步处理：打分 → 实体抽取 → embedding → buffer → seal（L1/L2 摘要，Source / Topic / Global 三棵树）。

```powershell
python -m aicorkit graph worker run-once
python -m aicorkit graph worker start
python -m aicorkit graph worker status
python -m aicorkit graph tree list --kind topic
python -m aicorkit graph tree digest --yes
python -m aicorkit graph entity list --hot
python -m aicorkit graph export -o graph.json
```

**Vault 与运维**

```powershell
python -m aicorkit graph vault open
python -m aicorkit graph vault index --yes
python -m aicorkit graph dashboard --yes
python -m aicorkit graph memory show
python -m aicorkit graph archivist file ./session.json --yes
python -m aicorkit graph daemon start --once
```

Obsidian 打开 vault 目录（`graph vault path` 输出路径），浏览 `INDEX.md` 与双链。

### Skill 生成

为 Agent 生成技能文件（默认 **一次生成三个**）：

```powershell
# 默认：aicorkit-outlook + aicorkit-graph + aicorkit-atlassian
python -m aicorkit skill -p cursor
python -m aicorkit skill -p kiro
python -m aicorkit skill -p claude

# 仅 Jira / Confluence
python -m aicorkit skill -p cursor --atlassian

# 仅 Outlook / meeting
python -m aicorkit skill -p cursor --outlook

# 仅知识库 Graph
python -m aicorkit skill -p cursor --graph
```

| 平台 | aicorkit-outlook | aicorkit-graph | aicorkit-atlassian |
|------|------------------|----------------|---------------------|
| Claude | `.claude/skills/aicorkit-outlook/` | `.claude/skills/aicorkit-graph/` | `.claude/skills/aicorkit-atlassian/` |
| Kiro | `.kiro/skills/aicorkit-outlook/` | `.kiro/skills/aicorkit-graph/` | `.kiro/skills/aicorkit-atlassian/` |
| Cursor | `.cursor/skills/aicorkit-outlook/` | `.cursor/skills/aicorkit-graph/` | `.cursor/skills/aicorkit-atlassian/` |

### Agent 确认规则

| 类型 | 示例 | 需要用户确认 |
|------|------|--------------|
| 只读 | `graph search` / `jira get-issue` / `confluence get-page` | 否 |
| 写入 | `graph ingest` / `jira add-comment` / `confluence update-page` / `outlook send-email` | 是（Jira/Confluence/Graph 用 `--yes`） |

## 调试

### 常见问题

**`python` 或 `aicorkit` 找不到**

- 使用 `python -m aicorkit ...` 代替直接调用 `aicorkit`
- 确认 Python 3.10+：`python --version`
- 开发安装：`pip install -e .`

**Outlook 报错 / 无响应**

- 确认 Outlook 桌面版已启动并登录
- 首次 COM 调用可能弹出授权对话框，需允许
- 在 PowerShell 中单独测试：`python -m aicorkit outlook list-emails -c 3`

**Graph `worker run-once` 返回 `processed: 0`**

- 正常：sync 内部已跑过 worker，队列已空
- 新 ingest 后若 job 堆积：`python -m aicorkit graph worker run-once`

**向量检索无结果**

- 检查 `graph.embed.provider` 是否为 `none`
- DashScope 需设置 `DASHSCOPE_API_KEY`
- 切换 provider 后需重新 ingest 以生成向量

**项目 config 未生效**

- 确认在项目目录下执行命令
- `python -m aicorkit config paths` 查看是否识别到 `project_config`

### 查看配置与路径

```powershell
python -m aicorkit config paths
python -m aicorkit config show
python -m aicorkit graph status
python -m aicorkit graph vault path
python -m aicorkit graph worker status
```

### 开发调试

```powershell
pip install -e ".[dev]"
pytest
```

Graph 设计细节见 [`docs/design-graph-knowledge-base.md`](docs/design-graph-knowledge-base.md)。

## 项目结构

按 **skill（能力域）** 分包，每个 skill 含业务逻辑 + 独立 CLI：

```
aicorkit/
├── pyproject.toml
├── README.md
├── docs/
└── aicorkit/
    ├── cli.py              # 主入口，注册各 skill 子命令
    ├── cli_common.py       # CLI 共用工具（JSON 输出等）
    ├── config.py           # 全局 + 项目 config 合并
    ├── skill.py            # SKILL.md 生成（跨 skill 元工具）
    ├── llm/                # ACP 后端（meeting 共用）
    ├── outlook/            # aicorkit-outlook
    │   ├── com.py          # Outlook COM 实现
    │   └── cli.py
    ├── meeting/            # aicorkit-outlook（meeting 部分）
    │   ├── listen.py       # STT → AI → TTS
    │   └── cli.py
    ├── graph/              # aicorkit-graph（本地知识库）
    │   ├── cli.py
    │   ├── sources/        # folder / outlook / web / notes
    │   └── ...
    ├── atlassian/          # aicorkit-atlassian
    │   ├── client.py       # REST 客户端
    │   ├── jira.py / confluence.py
    │   ├── jira_cli.py / confluence_cli.py / cli.py
    └── wxmsg/              # aicorkit-wxmsg
        ├── api.py
        └── cli.py
```

## 工作原理（Outlook）

```
python -m aicorkit outlook list-emails
  → aicorkit/outlook/cli.py
    → aicorkit/outlook/com.py
      → pywin32 → Outlook.Application COM
        → MAPI → Inbox → JSON 输出
```

Python 通过 pywin32 直接与 Outlook COM 通信，无需 MCP 服务器或 HTTP 中间层。

## 扩展新 skill

1. 在 `aicorkit/<skill>/` 下新增模块（如 `api.py`）与 `cli.py`（Click group）
2. 在 `aicorkit/cli.py` 中 `main.add_command(...)`
3. 在 `aicorkit/skill.py` 增加模板并运行 `python -m aicorkit skill -p cursor`
