aicorkit

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）

安装

从源码安装

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

可选依赖

Windows 运行方式

安装后 PATH 上的 aicorkit 是 aicorkit.cmd → python -m aicorkit（不生成 aicorkit.exe，避免与 .exe 探测冲突）。也可直接：

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

若以前装过留下 Scripts\aicorkit.exe，可删掉后重新 pip install -U aicorkit。

配置

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

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"

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

Graph 知识库

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

数据位置

一键 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。

工作区知识库（AICortex）

在网页「知识库」复制已填好的命令（base-url / token / 工作区 slug / collection）。登录后 graph search 默认同时查本地和云端。

python -m aicorkit graph remote login --base-url <api> --token mul_... --workspace <slug>
python -m aicorkit graph remote use --workspace <slug>
python -m aicorkit graph remote collections
python -m aicorkit graph search "架构方案"

日常改文档请在网页编辑；graph push 仅用于把本地已 ingest 的源一次性搬上去。

检索（只读，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

Agent 确认规则

调试

常见问题

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

查看配置与路径

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。

项目结构

按 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