AI-powered desktop tool orchestration CLI

Project description

aicorkit

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

环境要求

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

安装

从源码安装

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，可用模块方式调用（推荐）：

python -m aicorkit --help
python -m aicorkit graph status

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

配置

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

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

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）：

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

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

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

使用说明

Outlook

# 只读
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 独立。

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 凭据。

# 连接测试
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（推荐）

# 最小：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

初始化与状态

python -m aicorkit graph init
python -m aicorkit graph status

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

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

数据源同步

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 可直接调用）

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：

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 三棵树）。

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 与运维

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 生成技能文件（默认 一次生成三个）：

# 默认：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.11+：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

查看配置与路径

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

开发调试

pip install -e ".[dev]"
pytest

Graph 设计细节见 docs/design-graph-knowledge-base.md。

项目结构

aicorkit/
├── pyproject.toml
├── README.md
├── docs/
│   └── design-graph-knowledge-base.md
└── aicorkit/
    ├── cli.py              # 主 CLI（outlook / meeting / config / skill）
    ├── config.py           # 全局 + 项目 config 合并
    ├── outlook.py          # Outlook COM
    ├── skill.py            # SKILL.md 生成
    ├── meeting/            # 会议 STT/LLM/TTS
    ├── llm/                # ACP 后端
    └── graph/              # 本地知识库
        ├── ingest.py       # 入库
        ├── retrieval/      # search / query / walk
        ├── pipeline/       # worker / jobs
        ├── tree/           # 摘要树 seal
        ├── sources/        # folder / outlook / web / notes
        ├── store/          # SQLite + vectors
        └── vault/          # Obsidian hub / INDEX

工作原理（Outlook）

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

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

扩展新工具

在 aicorkit/ 下新增模块（如 foo.py）
在 aicorkit/cli.py 注册 Click 子命令
更新 aicorkit/skill.py 并运行 python -m aicorkit skill -p kiro

Project details

Release history Release notifications | RSS feed

This version

0.1.6

Jun 17, 2026

0.1.5

Jun 17, 2026

0.1.4

Jun 16, 2026

0.1.3

Jun 14, 2026

0.1.2

Jun 13, 2026

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

aicorkit-0.1.6.tar.gz (110.6 kB view details)

Uploaded Jun 17, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

aicorkit-0.1.6-py3-none-any.whl (128.2 kB view details)

Uploaded Jun 17, 2026 Python 3

File details

Details for the file aicorkit-0.1.6.tar.gz.

File metadata

Download URL: aicorkit-0.1.6.tar.gz
Upload date: Jun 17, 2026
Size: 110.6 kB
Tags: Source
Uploaded using Trusted Publishing? No
Uploaded via: twine/6.2.0 CPython/3.13.2

File hashes

Hashes for aicorkit-0.1.6.tar.gz
Algorithm	Hash digest
SHA256	`e5c4fab7764d0c49e5bd1e5134d46908c8602d5692ffd8c9ae10d3193e2a3d89`
MD5	`3c3562d8e7c3a5ee7c6486e3afbb04b1`
BLAKE2b-256	`65f732603a968f25f1f8eacb7b4b0d1716a49de33badef7419169ca5cb8a565d`

See more details on using hashes here.

File details

Details for the file aicorkit-0.1.6-py3-none-any.whl.

File metadata

Download URL: aicorkit-0.1.6-py3-none-any.whl
Upload date: Jun 17, 2026
Size: 128.2 kB
Tags: Python 3
Uploaded using Trusted Publishing? No
Uploaded via: twine/6.2.0 CPython/3.13.2

File hashes

Hashes for aicorkit-0.1.6-py3-none-any.whl
Algorithm	Hash digest
SHA256	`71d09df682c6ddae310ab3e8170c15e05a72ece57cab0e765c4fe4949fb5d7c0`
MD5	`694b7d403a7f83ae9192590846c61b40`
BLAKE2b-256	`adb0e94c8251ede960aa88a7aba51344f01ca9b431fcbc3687ce3bd5e1434f57`

See more details on using hashes here.

aicorkit 0.1.6

Navigation

Verified details

Maintainers

Unverified details

Meta

Project description

aicorkit

环境要求

安装

从源码安装

可选依赖

Windows 运行方式

配置

使用说明

Outlook

Meeting（会议语音）

Jira / Confluence

Graph 知识库

Skill 生成

Agent 确认规则

调试

常见问题

查看配置与路径

开发调试

项目结构

工作原理（Outlook）

扩展新工具

Project details

Verified details

Maintainers

Unverified details

Meta

Release history Release notifications | RSS feed

Download files

Source Distribution

Built Distribution

File details

File metadata

File hashes

File details

File metadata

File hashes