AIDEV 智能体接入与资源初始化方案

# 使用平台提供、当前网络可访问的可信包源
export BKAI_PIP_INDEX_URL='<bkai-init 包源的 /simple 地址>'
export BKAI_DEPENDENCY_INDEX_URL='<公共依赖源的 /simple 地址>'

python3.11 -m venv .venv-bkai-init
. .venv-bkai-init/bin/activate

python -m pip install \
  --index-url "$BKAI_PIP_INDEX_URL" \
  --extra-index-url "$BKAI_DEPENDENCY_INDEX_URL" \
  "bkai-init==0.1.1"

python -m pip show bkai-init
bkai-init --help

bkai-init init ./bk-job --agent-code ai-job --name "作业助手"

# 替换为目标空间 ID；CLI 需要显式传入 --space
export BKAI_SPACE_ID='<目标空间ID>'
bkai-init validate -f ./bk-job/bkai.yaml --space "$BKAI_SPACE_ID"

export BKAI_INIT_IMAGE='<可访问镜像仓库>/bk-aidev-init:0.1.1'
podman pull --platform linux/amd64 "$BKAI_INIT_IMAGE"
podman run --rm --platform linux/amd64 "$BKAI_INIT_IMAGE" --help

# 当前目录包含 bk-job/；先在宿主设置目标空间
export BKAI_SPACE_ID='<目标空间ID>'
podman run --rm --platform linux/amd64 -v "$PWD/bk-job:/bk-job:ro" \
  "$BKAI_INIT_IMAGE" validate -f /bk-job/bkai.yaml --space "$BKAI_SPACE_ID"

# 在宿主直接配置连接信息，再传入容器
export BK_API_URL_TMPL='https://bkapi.example.com/api/{api_name}/{stage}'
export BKAI_APP_CODE='<应用编码>'
export BKAI_APP_SECRET='<应用密钥>'
podman run --rm --platform linux/amd64 \
  --env BK_API_URL_TMPL --env BKAI_APP_CODE --env BKAI_APP_SECRET \
  -v "$PWD/bk-job:/bk-job:ro" "$BKAI_INIT_IMAGE" diff \
  -f /bk-job/bkai.yaml --tenant-id system --space "$BKAI_SPACE_ID"

ARG BKAI_INIT_IMAGE
FROM ${BKAI_INIT_IMAGE}
COPY --chown=10001:10001 ./bk-job /bk-job

/bk-job/
├── bkai.yaml
├── agents/
│   ├── bk_job_ai.yaml
│   └── bk_job_exec.yaml
├── collections/
│   └── job_role.yaml
├── skills/
│   └── job_skill/
│       ├── skill.yaml
│       ├── Dockerfile     # 可选；引用基础镜像
│       └── SKILL.md
├── knowledgebases/
│   └── bk_job_docs/
│       ├── knowledgebase.yaml
│       ├── README.md
│       └── guides/
│           └── execute.md
└── tools/                  # 预留

apiVersion: bkai.tencent.com/v1
kind: AgentPackage
metadata:
  name: bk-job
  version: "1.0.0"
resources:
  - collections/job_role.yaml
  - skills/job_skill
  - knowledgebases/bk_job_docs
  - agents/bk_job_exec.yaml
  - agents/bk_job_ai.yaml

# AIDEV Agent CLI Manifest v1
apiVersion: bkai.tencent.com/aidev-agent/v1
kind: Agent

metadata:
  code: ai-job
  name: 蓝鲸作业智能助手
  description: 面向蓝鲸作业平台的智能助手

spec:
  user_scope: public          # 所有人可使用；custom 为指定人，省略则不修改使用范围
  admins: []                  # 按需填写 login_name；自动转为 bk_username，仅追加，空值不处理
  prompt:
    type: inline
    content: |
      ## Role

      蓝鲸作业智能助手

      ## Constraints

      - 仅回答与蓝鲸作业平台相关的问题。

  model:
    llm_code: aidev-chat-auto
    fallback_model: null
    temperature: 0.7
    context_window: 16         # 上下文轮数
    llm_token_limit: 28000
    max_tokens: 4096
    tool_output_compress_thrd: 4096

  conversation_settings:
    opening_remark: 你好，我可以帮助你查询作业执行情况。
    predefined_questions:
      - 如何查询作业执行状态？
    enable_chat_session: true
    enable_word_selection_popup: true
    commands:
      - id: query_job_status
        name: 查询作业状态
        icon: null
        agent_code: ai-job
        alias: null
        content: |
          查询作业 {{ job_id }} 在 {{ environment }} 环境中的执行状态。
          最多返回 {{ limit }} 条记录。
          补充信息：{{ context }}
        components:
          - type: text
            key: job_id
            name: 作业 ID
            placeholder: 请输入作业 ID
            default: ""
            required: true
            hide: false
          - type: select
            key: environment
            name: 环境
            placeholder: 请选择环境
            default: test
            required: true
            hide: false
            options:
              - label: 测试
                value: test
              - label: 生产
                value: production
          - type: number
            key: limit
            name: 返回数量
            default: 10
            min: 1
            max: 100
            required: false
            hide: false
          - type: textarea
            key: context
            name: 补充信息
            placeholder: 输入或引用需要分析的文本
            default: ""
            rows: 4
            required: false
            hide: false
        enable_fill_back: true
        fill_back_component_key: context
        fill_regx: null
        support_upload:
          vision: false
          file: false

      # 引用子智能体指令：按 agent_code 和 id 定位
      - id: execute_job
        agent_code: ai-job-exec
        alias: 作业执行助手

  subagents:
    - code: ai-job-exec

  mcps:
    - type: apigw
      code: bk-job-apigw-mcp
      is_selected_all: false
      selected_tools:
        - tool_name: get_job_status

  skills:
    - code: job_skill
      envs:
        - key: BK_JOB_MODULE
          value: bk-job

  knowledgebases:
    items:
      - code: bk_job_docs
    retriever_code: ""
    query_function: mixed
    recall_channels: [dense, sparse]
    rrf_weights:
      dense: 0.7
      sparse: 0.3
    document_fragment_count: 20
    polish: true
    origin: false
    is_response_when_no_knowledgebase_match: true
    rejection_message: 未找到相关作业文档，请补充问题信息。

  tools: []                   # 本期暂不支持

spec:
  user_scope: public  # 所有人可使用；指定人使用填 custom

apiVersion: bkai.tencent.com/v1
kind: Collection

metadata:
  code: bk_job_role
  name: 蓝鲸作业专家

spec:
  collection_type: role
  generate_type: space
  is_public: false
  tag_names: []
  content:
    - role: system
      content: |
        你是蓝鲸作业专家，仅回答与作业平台相关的问题。
    - role: user
      content: 如何查询作业执行状态？
    - role: assistant
      content: 我可以帮助你查询作业执行状态，请提供作业 ID。

spec:
  prompt:
    type: collection
    code: bk_job_role

spec:
  mcps:
    - type: apigw
      code: bk-job-apigw-mcp
      is_selected_all: false
      selected_tools:
        - tool_name: get_job_status

spec:
  skills:
    - code: job_skill
      envs:
        - key: BK_JOB_MODULE
          value: bk-job

apiVersion: bkai.tencent.com/v1
kind: Skill
metadata:
  code: job_skill
  name: 作业查询 Skill
  # 不填 version，由平台根据 ZIP 内容自动确定版本
  description: 查询作业执行信息
spec:
  generate_type: space
  is_public: false
  tag_names: []

FROM {{ SKILL_BASE_IMAGE | default("registry.example.com/team/skill:1.0") }}

apiVersion: bkai.tencent.com/aidev-agent/v1
kind: Agent
metadata:
  code: ai-job-exec
  name: 作业执行助手
spec:
  prompt:
    type: inline
    content: 你是作业执行助手，帮助用户理解任务信息。
  model:
    llm_code: aidev-chat-auto
    context_window: 16
  conversation_settings:
    commands:
      - id: execute_job
        name: 分析作业执行
        icon: null
        content: 请分析任务 {{ task_id }} 的执行信息。
        components:
          - type: text
            key: task_id
            name: 任务 ID
            required: true
  tools: []

spec:
  subagents:
    - code: ai-job-exec

  # 可选：引用该子智能体的已发布指令
  conversation_settings:
    commands:
      - id: execute_job
        agent_code: ai-job-exec
        alias: 作业执行助手

apiVersion: bkai.tencent.com/v1
kind: KnowledgeBase
metadata:
  code: bk_job_docs
  name: 作业平台知识库
  description: 作业平台使用文档
spec:
  generate_type: space
  is_public: false
  config: {}
  tag_names: []

spec:
  knowledgebases:
    items:
      - code: bk_job_docs
    retriever_code: ""
    query_function: mixed
    recall_channels: [dense, sparse]
    rrf_weights:
      dense: 0.7
      sparse: 0.3
    document_fragment_count: 20
    polish: true
    origin: false
    is_response_when_no_knowledgebase_match: true
    rejection_message: 未找到相关作业文档，请补充问题信息。

# 替换为目标环境的配置；不打印凭据
export BK_API_URL_TMPL='https://bkapi.example.com/api/{api_name}/{stage}'
export BKAI_APP_CODE='<应用编码>'
export BKAI_APP_SECRET='<应用密钥>'
export BKAI_SPACE_ID='<目标空间ID>'
# 可选：不传 username 默认 bk_admin；通常不需要 access_token
# export BKAI_USERNAME='bk_admin'
# export BKAI_ACCESS_TOKEN='<按需填写>'
# CLI 通过 --space 显式接收空间 ID

# 1. 校验本地配置
bkai-init validate -f /bk-job/bkai.yaml --space "$BKAI_SPACE_ID"

# 2. 查看清单涉及资源的线上配置
bkai-init show -f /bk-job/bkai.yaml --tenant-id system --space "$BKAI_SPACE_ID"

# 3. 对比本地配置与线上配置
bkai-init diff -f /bk-job/bkai.yaml --tenant-id system --space "$BKAI_SPACE_ID"

# 4. 预览完整主子智能体初始化计划
bkai-init plan -f /bk-job/bkai.yaml --space "$BKAI_SPACE_ID" --publish

# 5. 确认后同步并发布配置（先子后主）
bkai-init sync -f /bk-job/bkai.yaml \
  --tenant-id system --space "$BKAI_SPACE_ID" \
  --confirm --publish --publish_config_only=0

# 仅同步指定依赖；--resource 支持一个或多个
bkai-init sync -f /bk-job/bkai.yaml --space "$BKAI_SPACE_ID" --confirm \
  --resource skill/job_skill knowledgebase/bk_job_docs

# 查看一个资源的线上配置
bkai-init show -f /bk-job/bkai.yaml --space "$BKAI_SPACE_ID" \
  --resource agent/ai-job --format json

# 平台手工维护的主智能体整体跳过；未选资源不自动同步
bkai-init sync -f /bk-job/bkai.yaml --space "$BKAI_SPACE_ID" --confirm \
  --exclude-resource agent/ai-job

[3/8] 正在处理：Skill/job_skill
  配置：skills/job_skill/skill.yaml
  ✓ 打包完成
  ✓ 上传完成
  → 正在同步 Skill
      接口请求：POST https://bkapi.example.com/api/bk-aidev/prod/openapi/aidev/app/v1/skills/upsert/
  ✓ 同步完成

      【正在查询 MCP】bk-job-apigw-mcp agent_code: ai-job 成功

[3/8] 正在处理：Skill/job_skill
  配置：skills/job_skill/skill.yaml
  ✓ 打包完成
  ✓ 上传完成
  → 正在同步 Skill
      接口请求：POST https://bkapi.example.com/api/bk-aidev/prod/openapi/aidev/app/v1/skills/upsert/
      请求参数：
          {
            "skill_code": "job_skill",
            "space_id": "<目标空间ID>"
          }
      接口响应：[HTTP 500]
          {
            "error": {
              "code": 500,
              "message": "Incorrect string value for column skill_markdown"
            }
          }
  ✗ 同步 Skill失败：skill_markdown 字符编码不兼容

初始化已停止
  已完成 2 项，失败 1 项，未执行 5 项
  失败事项：Skill/job_skill
  失败步骤：同步 Skill
  排查建议：检查平台数据库字段字符集
  反馈信息：执行时间、CLI 版本、请求标识（服务端提供时）

bkai-init sync -f /bk-job/bkai.yaml --space "$BKAI_SPACE_ID" --confirm \
  --var SKILL_BASE_IMAGE=registry.example.com/team/skill:1.0 \
  --var SKILL_NAME=job_skill

import logging
import os
import sys

from bkai_init import BkaiInit

logging.basicConfig(level=logging.INFO, stream=sys.stdout)
api_url_template = os.environ["BK_API_URL_TMPL"]  # 使用下方含 {api_name}/{stage} 的统一模板
initializer = BkaiInit(
    base_url=api_url_template.format(api_name="bk-aidev", stage="prod"),
    app_code=os.environ["BKAI_APP_CODE"],
    app_secret=os.environ["BKAI_APP_SECRET"],
    bk_user_base_url=api_url_template.format(api_name="bk-user", stage="prod"),
    username=os.environ.get("BKAI_USERNAME"),  # 可选；不传默认 bk_admin（登录名）
    access_token=os.environ.get("BKAI_ACCESS_TOKEN"),  # 可选；通常可省略这一行
    tenant_id="system",
    space=os.environ["BKAI_SPACE_ID"],
    variables={"SKILL_BASE_IMAGE": "registry.example.com/team/skill:1.0"},
)
package = "/bk-job/bkai.yaml"
initializer.validate(package)
online = initializer.show(package, resources={"agent/ai-job"})
differences = initializer.diff(package, resources={"agent/ai-job"})
preview = initializer.plan(package, publish=True, publish_config_only=False)

# 写入操作：仅在调用方确认计划后执行
report = initializer.sync(package, publish=True, publish_config_only=False)

ARG BKAI_INIT_IMAGE
FROM ${BKAI_INIT_IMAGE}
COPY --chown=10001:10001 ./bk-job /bk-job

# 在当前终端直接执行，替换为目标环境的配置
export BK_API_URL_TMPL='https://bkapi.example.com/api/{api_name}/{stage}'
export BKAI_APP_CODE='<应用编码>'
export BKAI_APP_SECRET='<应用密钥>'
export BKAI_SPACE_ID='<目标空间ID>'

# 可选：不传 username 默认 bk_admin；通常不需要 access_token
# export BKAI_USERNAME='bk_admin'
# export BKAI_ACCESS_TOKEN='<按需填写>'

export BKAI_SPACE_ID='<目标空间ID>'
export BKAI_INIT_IMAGE='<可访问镜像仓库>/bk-aidev-init:0.1.1'
podman build --platform linux/amd64 --build-arg BKAI_INIT_IMAGE="$BKAI_INIT_IMAGE" -t bkai-init-demo:local .
podman run --rm --platform linux/amd64 bkai-init-demo:local validate \
  -f /bk-job/bkai.yaml --space "$BKAI_SPACE_ID"
podman run --rm --platform linux/amd64 \
  --env BK_API_URL_TMPL --env BKAI_APP_CODE --env BKAI_APP_SECRET \
  bkai-init-demo:local plan -f /bk-job/bkai.yaml \
  --tenant-id system --space "$BKAI_SPACE_ID" --publish
podman run --rm --platform linux/amd64 \
  --env BK_API_URL_TMPL --env BKAI_APP_CODE --env BKAI_APP_SECRET \
  bkai-init-demo:local sync -f /bk-job/bkai.yaml \
  --tenant-id system --space "$BKAI_SPACE_ID" \
  --confirm --publish --publish_config_only=0

podman run --rm -it --platform linux/amd64 --entrypoint sh \
  --env BK_API_URL_TMPL --env BKAI_APP_CODE --env BKAI_APP_SECRET \
  --env BKAI_SPACE_ID bkai-init-demo:local

bkai-init --help
bkai-init validate -f /bk-job/bkai.yaml --space "$BKAI_SPACE_ID"
bkai-init plan -f /bk-job/bkai.yaml \
  --tenant-id system --space "$BKAI_SPACE_ID"

# 确认计划后才执行写入；此命令仅同步草稿
bkai-init sync -f /bk-job/bkai.yaml \
  --tenant-id system --space "$BKAI_SPACE_ID" --confirm
# 需要发布时，在 plan 和 sync 中追加 --publish --publish_config_only=0

image:
  repository: registry.example.com/modules/bk-job-init
  tag: "1.0.0"
  pullPolicy: IfNotPresent

bkai:
  enabled: true
  tenantId: system
  space: "<目标空间ID>"   # 必填，替换为真实目标值
  packagePath: /bk-job/bkai.yaml
  excludeResources: []