Skip to content

feishu_api_integration.md

Latest commit

 

History

History
120 lines (89 loc) · 5.38 KB

feishu_api_integration.md

File metadata and controls

120 lines (89 loc) · 5.38 KB

Feishu API Integration Guide

This document outlines how to replace the sample local fixtures with real Feishu API integrations for ProjectAI.

1. Create a Feishu Application

  1. Log into the Feishu Developer Console.
  2. Create an enterprise self-built application and enable the Docs, Sheets, and IM permissions required for your scenario.
  3. Generate the app ID, app secret, and (if required) the tenant access token credentials.

2. Install Dependencies

ProjectAI only relies on the Python standard library by default. For API access install requests or the official Feishu SDK:

pip install requests

3. Configure Credentials

Update your configuration file (e.g. config/api_config.example.json) to enable API mode:

{
  "feishu": {
    "mode": "api",
    "api": {
      "app_id": "${FEISHU_APP_ID}",
      "app_secret": "${FEISHU_APP_SECRET}",
      "tenant_key": "${FEISHU_TENANT_KEY}",
      "document_ids": ["doccnXXXXXXXXXXXXXX"],
      "bitables": [
        {
          "app_token": "bascXXXXXXXXXXXXXX",
          "table_id": "tblXXXXXXXXXXXXXX",
          "fields": {
            "title": "任务名称",
            "owner": "负责人",
            "due_date": "计划完成时间",
            "status": "状态",
            "progress": "进度",
            "blockers": "阻塞",
            "tags": "标签",
            "updated_at": "更新时间"
          }
        }
      ],
      "chats": [
        {
          "chat_id": "oc_xxxxxxxxx",
          "related_task_field": "related_tasks",
          "severity_field": "severity"
        }
      ]
    }
  }
}

Export the sensitive values as environment variables before running ProjectAI:

export FEISHU_APP_ID="cli_xxx"
export FEISHU_APP_SECRET="xxx"
export FEISHU_TENANT_KEY="t-xxx"

The loader replaces ${VAR} placeholders with the corresponding environment variable values.

4. Implement the API Data Source

Implement the FeishuAPIDataSource class (see src/project_ai/data_sources/feishu_api.py) to:

  • Fetch document raw content via the Drive API. Parse TODO checkboxes (- [ ]) and bullet lists into tasks.
  • Query Bitable tables for structured task records and normalize to ProjectAI's task schema.
  • Read chat history using the IM Message API.
  • Convert timestamps to ISO-8601 strings so they align with the local fixtures.

Remember to handle pagination (page_token), rate limits, and token refresh. Store only the minimal fields required by the MVP (title, owner, due date, status, progress, blockers).

4.1 Required API Endpoints & Scopes

ProjectAI currently touches the following Feishu Open API endpoints:

Purpose Endpoint Scope Notes
Exchange app credentials for tenant_access_token POST /open-apis/auth/v3/tenant_access_token/internal auth:tenant_access_token (built-in) Cached in memory; refresh on 1-hour expiry.
Read document checklist content GET /open-apis/docx/v1/documents/{document_id}/raw_content docx:document:readonly Parsed for markdown checkboxes (- [ ]).
Pull Bitable records GET /open-apis/bitable/v1/apps/{app_token}/tables/{table_id}/records bitable:app Supports pagination via page_token.
Read chat messages GET /open-apis/im/v1/messages im:message Requires container_id_type=chat and chat-level permissions.

Depending on your workspace, you may also need:

  • POST /open-apis/docx/v1/documents/{document_id}/content when you want to push status updates back to the document.
  • GET /open-apis/drive/v1/files/{file_token}/meta to resolve owners or attachments referenced in TODOs.
  • GET /open-apis/bitable/v1/apps/{app_token}/tables if table IDs change frequently and need discovery.

Ensure the app is added to each document, Bitable, and group chat, otherwise the API returns permission denied.

4.2 Optional Analytics / Model APIs

The MVP ships with rule-based risk detection. For deeper analysis you can plug in an LLM or task-specific model via a service interface (e.g. extend RiskService). Recommended options:

  • Feishu / ByteDance Doubao APIs (/open-apis/ai/v1/chat/completions): Summarise chat discussions, infer hidden risks, or classify severity. Requires enabling the Feishu AI capability and storing API keys securely.
  • OpenAI / Azure OpenAI: Use GPT models to rate schedule slippage or generate mitigation suggestions. Wrap the request in a new LLMRiskAnalyzer that accepts task/context text and outputs structured risk hints.
  • Vector similarity models (e.g. text-embedding-3-small) to match new issues with historical incidents before ranking.

When introducing model endpoints, capture prompts & responses for traceability and add fallbacks in case the external service is unavailable.

5. Scheduling and Automation

Once API ingestion works, run ProjectAI on a schedule (e.g. cron or Airflow). Direct the notifications output to your Feishu bot or webhook service.

6. Security Considerations

  • Keep credentials in a secrets manager or environment variables; never commit them.
  • Apply the principle of least privilege when requesting API scopes.
  • Audit and log API calls to monitor failures and retries.

Use this guide as a starting point to extend ProjectAI from local demo data to your production Feishu workspace.