fresh-auth

Fresh Auth Workspace CLI

将此技能用作安全、具备身份感知能力地访问 Microsoft 365（Graph）和 Notion 的唯一入口。

使用此技能的场景

• 通过 office-cli 执行云盘操作、访问 OneDrive 文件和创建共享链接。
• 通过 office-cli 执行 Outlook 收件箱、搜索、发送和回复操作。
• 通过 office-cli 查找日历和查看日程安排。
• 通过 office-cli 查找人员。
• 通过 notion-query 搜索和查询 Notion 数据库、读写页面以及转换 markdown。
• 在一个工作流中混合使用 Office 和 Notion 数据的任何请求。

安全模型

• 使用 Auth Service Proxy https://auth.freshhub.ai 执行 Microsoft Graph 和 Notion 操作。
• 使用 Agent 会话授权和 OAuth 审批，绝不使用原始提供商令牌。
• 将 ~/.config/fresh-auth/agent-session 的权限保持为安全模式（600）。
• 为兼容性，仍会读取旧版 ~/.config/office-cli/agent-session。
• 将密钥存储在环境变量中。
• 将 OPENROUTER_API_KEY 用于 Office PDF/图像转换。
• 仅在需要覆盖默认代理端点时使用 AUTH_SERVICE_URL。

运行时先决条件

• 安装 Node.js（18+），以运行 scripts/office-cli.js 和 scripts/notion-query.js。
• 在此技能文件夹中运行命令，或导出明确的路径。

# Resolve skill location for common installers
export FRESH_AUTH_DIR="${HOME}/.agents/skills/fresh-auth"
[ -d "$FRESH_AUTH_DIR" ] || export FRESH_AUTH_DIR="${HOME}/.codex/skills/fresh-auth"

export OFFICE_CLI="${FRESH_AUTH_DIR}/scripts/office-cli.js"
export NOTION_CLI="${FRESH_AUTH_DIR}/scripts/notion-query.js"
export AUTH_SERVICE_URL="https://auth.freshhub.ai"

# Quick command discovery
[ -f "$OFFICE_CLI" ] && node "$OFFICE_CLI" status
[ -f "$NOTION_CLI" ] && node "$NOTION_CLI" status

随附脚本

• scripts/office-cli.js，用于执行由 Microsoft Graph 提供支持的云盘、邮件、日历和人员操作。
• scripts/notion-query.js，用于通过认证服务代理执行 Notion 读写工作流。

Office + Graph：标准流程

授予 Graph 支持的工具访问权限时，请遵循此流程。

# Register and create grants
node "$OFFICE_CLI" login
node "$OFFICE_CLI" request drive
node "$OFFICE_CLI" request mail
node "$OFFICE_CLI" request cal
node "$NOTION_CLI" request

# Verify active grants
node "$OFFICE_CLI" status
node "$NOTION_CLI" status

Agent 辅助验证交接

当 Agent 运行 login 或 request 时，CLI 可能会输出供用户审批的验证 URL 和代码。

1. Agent 运行认证命令并准确获取验证输出。
2. Agent 将验证 URL 和代码发送给用户（不要转述）。
3. 优先分享预填充的 URL 格式： https://auth.freshhub.ai/agent/verify?code=<CODE>
4. 用户打开 URL，确认代码，点击 Verify Code，然后在下一屏手动点击 Approve。
5. Agent 等待审批轮询完成，然后继续执行所请求的任务。

如果审批失败，请重复此流程，并在用户输入代码前确认其已登录预期的 Fresh Auth 账号。

命令速查：Office CLI

云盘 / Graph 存储

node "$OFFICE_CLI" drive list
node "$OFFICE_CLI" drive list "/Documents"
node "$OFFICE_CLI" drive search "Quarterly report"
node "$OFFICE_CLI" drive download <file-id> out.docx
node "$OFFICE_CLI" drive content <file-id>
node "$OFFICE_CLI" drive convert <file-id> --output=notes.md
node "$OFFICE_CLI" drive share <file-id> --type edit
node "$OFFICE_CLI" drive share <file-id> --anyone
node "$OFFICE_CLI" drive permissions <file-id>
node "$OFFICE_CLI" drive unshare <file-id> <permission-id>

邮件 / 电子邮件

node "$OFFICE_CLI" mail inbox
node "$OFFICE_CLI" mail inbox --count 50
node "$OFFICE_CLI" mail unread
node "$OFFICE_CLI" mail search "team update"
node "$OFFICE_CLI" mail read <message-id>
node "$OFFICE_CLI" mail send --to "[email protected]" --subject "Brief" --body "Thanks for the update"
node "$OFFICE_CLI" mail send --to "brad" --subject "Quick check" --body "Approved" --yes
node "$OFFICE_CLI" mail reply <message-id> --body "Got it."
node "$OFFICE_CLI" mail reply-all <message-id> --body "Thanks everyone."

日历

node "$OFFICE_CLI" cal today
node "$OFFICE_CLI" cal tomorrow
node "$OFFICE_CLI" cal events --days 14
node "$OFFICE_CLI" cal events --full

人员查找（Graph 联系人助手）

node "$OFFICE_CLI" people "brad"
node "$OFFICE_CLI" people "brad" --verbose

Notion 命令速查

node "$NOTION_CLI" login
node "$NOTION_CLI" request
node "$NOTION_CLI" status
node "$NOTION_CLI" me
node "$NOTION_CLI" find-db "my database"
node "$NOTION_CLI" search "my database"
node "$NOTION_CLI" get-db <database-id>
node "$NOTION_CLI" query-db <database-id>
node "$NOTION_CLI" get-page <page-id>
node "$NOTION_CLI" get-markdown <page-id>
node "$NOTION_CLI" create <database-id> "Title" -p "Status=In progress" -p "Priority=High"
node "$NOTION_CLI" update <page-id> -p "Status=Done"
node "$NOTION_CLI" set-body <page-id> -
node "$NOTION_CLI" append-body <page-id> -

如果不知道数据库 ID，请先使用 find-db。它会返回数据库的 id、title 和 url，可直接将 ID 复制到 get-db、query-db 或 create 中。

Notion 待办事项助手

# Optional: enable shortcuts for a specific Notion backlog database
export NOTION_BACKLOG_DB_ID="<database-id>"

node "$NOTION_CLI" backlog
node "$NOTION_CLI" backlog "In Progress"
node "$NOTION_CLI" create-backlog "New task"

多工具使用模式

• 先运行 people，然后运行 mail send --to <resolved email>，以更安全地解析身份。
• 使用 search 或 query-db 获取 Notion 任务，然后通过 append-body 添加上下文。
• 使用 drive convert 将云盘中的会议 PDF 转换为 markdown，然后通过 append-body 将笔记存入 Notion。

错误处理

• no_agent_session：运行 node "$OFFICE_CLI" login。
• no_grant：运行 node "$OFFICE_CLI" request <drive|mail|cal>。
• token expired：运行 node "$OFFICE_CLI" status，并按照返回的重新授权 URL 操作。
• no agent session（Notion）：运行 node "$NOTION_CLI" login。
• no grant（Notion）：运行 node "$NOTION_CLI" request。
• 缺少 NOTION_BACKLOG_DB_ID：设置该变量，或改用通用的 query-db/create 命令，而不是待办事项快捷命令。
• Microsoft 账号未关联：按照 Graph 代理响应中输出的 URL 操作。
• Notion 账号未关联：按照 CLI 输出的 Notion 关联 URL 操作。

公开发布检查

• 代理 URL 应可通过 AUTH_SERVICE_URL 配置。
• 不要在技能输出中嵌入 API 密钥或会话 ID。
• 默认让所有命令都指向 https://auth.freshhub.ai。
• 在此技能的 scripts/ 文件夹中包含两个 CLI，以便独立安装。
• 在入门文档中提及 Microsoft 365 和 Notion 的功能，因为这是面向用户的统一访问路径。