huly-api

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Huly API

Overview

概述

Use this skill whenever swarm agents need durable communication in Huly:

```
tracker
```
tasks board (issues)
```
chunter
```
channels (chat messages)
```
document
```
teamspaces (mission docs)

Every autonomous mission should update all three surfaces. Default destinations for this workspace:

Tracker issues board:

DefaultProject

(

https://huly.proompteng.ai/workbench/proompteng/tracker/tracker%3Aproject%3ADefaultProject/issues

)

Documents teamspace:
```
PROOMPTENG
```

Chat channel URL:

https://huly.proompteng.ai/workbench/proompteng/chunter/chunter%3Aspace%3AGeneral%7Cchunter%3Aclass%3AChannel?message

当swarm Agent需要在Huly中实现持久化通信时使用此技能：

```
tracker
```
任务看板（issues）
```
chunter
```
频道（聊天消息）
```
document
```
团队空间（任务文档）

每个自主任务都需要更新这三个界面。此工作空间的默认目标：

Tracker issues看板:

DefaultProject

(

https://huly.proompteng.ai/workbench/proompteng/tracker/tracker%3Aproject%3ADefaultProject/issues

)

文档团队空间:
```
PROOMPTENG
```

聊天频道URL:

https://huly.proompteng.ai/workbench/proompteng/chunter/chunter%3Aspace%3AGeneral%7Cchunter%3Aclass%3AChannel?message

Required Environment

所需环境

Load credentials from the

huly-api

Kubernetes secret via AgentRun

spec.secrets

HULY_API_BASE_URL

(should target transactor, for example

http://transactor.huly.svc.cluster.local

)

HULY_BASE_URL

(optional human-facing base URL, often

http://front.huly.svc.cluster.local

)

```
HULY_API_TOKEN
```
(bearer token)
Optional:
- ```
HULY_WORKSPACE
```
  (workspace slug for operator context)
- ```
HULY_WORKSPACE_ID
```
  (workspace UUID; helper can also infer from JWT)
- ```
HULY_PROJECT
```
  (task board project identifier/name/id)
- ```
HULY_TEAMSPACE
```
  (document teamspace name/id)
- ```
HULY_CHANNEL
```
  (chat channel name/id)
- per-agent tokens:
```
HULY_API_TOKEN_<SWARM_AGENT_IDENTITY>
```
  or
```
HULY_API_TOKEN_<SWARM_AGENT_WORKER_ID>
```

通过AgentRun的

spec.secrets

从

huly-api

Kubernetes secret中加载凭证。

HULY_API_BASE_URL

（需指向事务处理器，例如

http://transactor.huly.svc.cluster.local

）

```
HULY_BASE_URL
```
（可选的面向用户的基础URL，通常为
```
http://front.huly.svc.cluster.local
```
）
```
HULY_API_TOKEN
```
（Bearer令牌）
可选配置：
- ```
HULY_WORKSPACE
```
  （操作员上下文的工作空间slug）
- ```
HULY_WORKSPACE_ID
```
  （工作空间UUID；辅助工具也可从JWT中推断）
- ```
HULY_PROJECT
```
  （任务看板项目标识符/名称/id）
- ```
HULY_TEAMSPACE
```
  （文档团队空间名称/id）
- ```
HULY_CHANNEL
```
  （聊天频道名称/id）
- 单Agent令牌：
```
HULY_API_TOKEN_<SWARM_AGENT_IDENTITY>
```
  或
```
HULY_API_TOKEN_<SWARM_AGENT_WORKER_ID>
```

Helper Script

辅助脚本

Use

scripts/huly-api.py

使用

scripts/huly-api.py

。

Mandatory channel interaction loop

强制频道交互流程

For every mission stage, run this in order:

Read recent channel history:

bash

python3 skills/huly-api/scripts/huly-api.py \
  --operation list-channel-messages \
  --worker-id "${SWARM_AGENT_WORKER_ID}" \
  --worker-identity "${SWARM_AGENT_IDENTITY}" \
  --require-worker-token \
  --channel "${ACTIVE_HULY_CHANNEL}" \
  --limit 30

React to at least one relevant teammate message by posting a natural direct reply with decision impact in-thread:

bash

python3 skills/huly-api/scripts/huly-api.py \
  --operation post-channel-message \
  --worker-id "${SWARM_AGENT_WORKER_ID}" \
  --worker-identity "${SWARM_AGENT_IDENTITY}" \
  --require-worker-token \
  --channel "${ACTIVE_HULY_CHANNEL}" \
  --reply-to-message-id "${RELEVANT_MESSAGE_ID}" \
  --message "Thanks for the context. I picked this up and I am implementing X next."

Post a worker-authored stage update after completing the mission action:

bash

python3 skills/huly-api/scripts/huly-api.py \
  --operation post-channel-message \
  --worker-id "${SWARM_AGENT_WORKER_ID}" \
  --worker-identity "${SWARM_AGENT_IDENTITY}" \
  --require-worker-token \
  --channel "${ACTIVE_HULY_CHANNEL}" \
  --message "${OWNER_UPDATE_MESSAGE}"

每个任务阶段都需要按以下顺序执行：

读取最近的频道历史：

bash

python3 skills/huly-api/scripts/huly-api.py \
  --operation list-channel-messages \
  --worker-id "${SWARM_AGENT_WORKER_ID}" \
  --worker-identity "${SWARM_AGENT_IDENTITY}" \
  --require-worker-token \
  --channel "${ACTIVE_HULY_CHANNEL}" \
  --limit 30

至少回复一条相关的队友消息，在帖子中发布具有决策影响的自然直接回复：

bash

python3 skills/huly-api/scripts/huly-api.py \
  --operation post-channel-message \
  --worker-id "${SWARM_AGENT_WORKER_ID}" \
  --worker-identity "${SWARM_AGENT_IDENTITY}" \
  --require-worker-token \
  --channel "${ACTIVE_HULY_CHANNEL}" \
  --reply-to-message-id "${RELEVANT_MESSAGE_ID}" \
  --message "Thanks for the context. I picked this up and I am implementing X next."

完成任务操作后发布Worker撰写的阶段更新：

bash

python3 skills/huly-api/scripts/huly-api.py \
  --operation post-channel-message \
  --worker-id "${SWARM_AGENT_WORKER_ID}" \
  --worker-identity "${SWARM_AGENT_IDENTITY}" \
  --require-worker-token \
  --channel "${ACTIVE_HULY_CHANNEL}" \
  --message "${OWNER_UPDATE_MESSAGE}"

Mission-level sync (recommended)

任务级同步（推荐）

bash

python3 skills/huly-api/scripts/huly-api.py \
  --operation upsert-mission \
  --worker-id "${SWARM_AGENT_WORKER_ID}" \
  --worker-identity "${SWARM_AGENT_IDENTITY}" \
  --mission-id jangar-discover-20260302 \
  --title "Jangar discover cycle" \
  --summary "Top platform risks and next actions" \
  --details "Includes evidence, risk deltas, and PR links" \
  --stage discover \
  --status running \
  --swarm-agent-worker-id "${SWARM_AGENT_WORKER_ID}" \
  --swarm-agent-identity "${SWARM_AGENT_IDENTITY}" \
  --message "${OWNER_UPDATE_MESSAGE}" \
  --project "DefaultProject" \
  --teamspace "PROOMPTENG" \
  --channel "general"

This creates/updates:

one task-board issue
one mission document
one channel message

bash

python3 skills/huly-api/scripts/huly-api.py \
  --operation upsert-mission \
  --worker-id "${SWARM_AGENT_WORKER_ID}" \
  --worker-identity "${SWARM_AGENT_IDENTITY}" \
  --mission-id jangar-discover-20260302 \
  --title "Jangar discover cycle" \
  --summary "Top platform risks and next actions" \
  --details "Includes evidence, risk deltas, and PR links" \
  --stage discover \
  --status running \
  --swarm-agent-worker-id "${SWARM_AGENT_WORKER_ID}" \
  --swarm-agent-identity "${SWARM_AGENT_IDENTITY}" \
  --message "${OWNER_UPDATE_MESSAGE}" \
  --project "DefaultProject" \
  --teamspace "PROOMPTENG" \
  --channel "general"

这将创建/更新：

1个任务看板issue
1个任务文档
1个频道消息

Single-surface operations

单界面操作

bash

python3 skills/huly-api/scripts/huly-api.py --operation create-issue --title "..." --mission-id "..."
python3 skills/huly-api/scripts/huly-api.py --operation create-document --title "..." --mission-id "..."
python3 skills/huly-api/scripts/huly-api.py --operation repair-project-issues --project "DefaultProject" --limit 500
python3 skills/huly-api/scripts/huly-api.py --operation repair-project-issues --project "DefaultProject" --limit 500 --fill-empty-issue-descriptions
python3 skills/huly-api/scripts/huly-api.py --operation dedupe-project-mission-issues --project "DefaultProject" --limit 1000 --dry-run
python3 skills/huly-api/scripts/huly-api.py --operation repair-teamspace-documents --teamspace "PROOMPTENG" --limit 500
python3 skills/huly-api/scripts/huly-api.py --operation post-channel-message --message "..."
python3 skills/huly-api/scripts/huly-api.py --operation post-channel-message --channel "general" --reply-to-message-id "<parent-message-id>" --message "In-thread reply"
python3 skills/huly-api/scripts/huly-api.py --operation list-channel-messages --channel "general" --limit 30
python3 skills/huly-api/scripts/huly-api.py --operation account-info --worker-id "${SWARM_AGENT_WORKER_ID}" --require-worker-token
python3 skills/huly-api/scripts/huly-api.py --operation verify-chat-access --worker-id "${SWARM_AGENT_WORKER_ID}" --worker-identity "${SWARM_AGENT_IDENTITY}" --require-worker-token --channel "general" --message "Hi team, I am starting this stage and will post progress here."

bash

python3 skills/huly-api/scripts/huly-api.py --operation create-issue --title "..." --mission-id "..."
python3 skills/huly-api/scripts/huly-api.py --operation create-document --title "..." --mission-id "..."
python3 skills/huly-api/scripts/huly-api.py --operation repair-project-issues --project "DefaultProject" --limit 500
python3 skills/huly-api/scripts/huly-api.py --operation repair-project-issues --project "DefaultProject" --limit 500 --fill-empty-issue-descriptions
python3 skills/huly-api/scripts/huly-api.py --operation dedupe-project-mission-issues --project "DefaultProject" --limit 1000 --dry-run
python3 skills/huly-api/scripts/huly-api.py --operation repair-teamspace-documents --teamspace "PROOMPTENG" --limit 500
python3 skills/huly-api/scripts/huly-api.py --operation post-channel-message --message "..."
python3 skills/huly-api/scripts/huly-api.py --operation post-channel-message --channel "general" --reply-to-message-id "<parent-message-id>" --message "In-thread reply"
python3 skills/huly-api/scripts/huly-api.py --operation list-channel-messages --channel "general" --limit 30
python3 skills/huly-api/scripts/huly-api.py --operation account-info --worker-id "${SWARM_AGENT_WORKER_ID}" --require-worker-token
python3 skills/huly-api/scripts/huly-api.py --operation verify-chat-access --worker-id "${SWARM_AGENT_WORKER_ID}" --worker-identity "${SWARM_AGENT_IDENTITY}" --require-worker-token --channel "general" --message "Hi team, I am starting this stage and will post progress here."

Raw HTTP mode (debug)

原生HTTP模式（调试用）

bash

python3 skills/huly-api/scripts/huly-api.py --operation http --method GET --path /api/v1/account/<workspace-id>

bash

python3 skills/huly-api/scripts/huly-api.py --operation http --method GET --path /api/v1/account/<workspace-id>

Operating Rules

操作规则

Every mission stage must publish artifacts to all three Huly modules: tasks, channels, and docs.
Each swarm agent should authenticate with its own Huly organization account (no shared actor credentials).
Always target Tracker
```
DefaultProject
```
issues and Docs
```
PROOMPTENG
```
teamspace unless a run explicitly overrides them.
Resolve
```
ACTIVE_HULY_CHANNEL
```
dynamically from runtime context (prefer
```
swarmRequirementChannel
```
, then
```
HULY_CHANNEL
```
, then default).
Read channel history before taking action, then react to relevant teammate messages with explicit in-thread follow-up replies using
```
--reply-to-message-id
```
.
Use
```
--require-worker-token
```
for dedicated-account checks so shared fallback tokens are rejected.

For strict identity mapping, set per-worker

HULY_EXPECTED_ACTOR_ID_<SWARM_AGENT_IDENTITY>

and use

--require-expected-actor-id

Run
```
verify-chat-access
```
before autonomous delivery stages with a worker-authored
```
--message
```
.
Include
```
swarmAgentWorkerId
```
and
```
swarmAgentIdentity
```
in issue/document artifacts.
Keep channel messages human-readable by default; avoid appending metadata blocks.
- If you need metadata in chat for a specific audit/debug flow, use
```
--append-channel-metadata
```
  .
- ```
upsert-mission
```
  automatically infers these fields from
```
--worker-id/--worker-identity
```
  (or
```
SWARM_AGENT_WORKER_ID
```
  /
```
SWARM_AGENT_IDENTITY
```
  ) if explicit
```
--swarm-agent-worker-id
```
  /
```
--swarm-agent-identity
```
  flags are not provided.
Keep channel updates concise, written by the worker, and linked to issue/doc/PR/deploy evidence.
Issue descriptions must be long-form and knowledge-base quality. The helper now stores issue descriptions through collaborator refs (not raw inline markdown) so tracker descriptions reliably render and persist.
```
upsert-mission
```
now reuses existing mission issues by mission id prefix (
```
[mission:<id>]
```
) to avoid duplicate ticket creation.
Use
```
repair-project-issues
```
to migrate legacy issues that still have inline markdown/plain text in
```
Issue.description
```
.
Use
```
repair-project-issues --fill-empty-issue-descriptions
```
when historical issues have truly empty description fields.
Use
```
dedupe-project-mission-issues
```
to move older duplicate mission issues to
```
Canceled
```
while keeping the most recent active issue.
Document content must be long-form and knowledge-base quality. The helper now stores mission document bodies through collaborator content refs (not raw inline markdown) so Huly editor/collaborator consistently loads and renders content.
Use
```
repair-teamspace-documents
```
to migrate legacy docs that still have inline markdown in
```
Document.content
```
.
If Huly auth fails, stop and return a clear unblock request instead of silently continuing.

每个任务阶段必须将产物发布到所有三个Huly模块：任务、频道和文档。
每个swarm Agent都应使用自己的Huly组织账户进行身份验证（不得共享账号凭证）。
除非运行时显式覆盖，否则始终指向Tracker的
```
DefaultProject
```
issues和文档的
```
PROOMPTENG
```
团队空间。
从运行时上下文中动态解析
```
ACTIVE_HULY_CHANNEL
```
（优先使用
```
swarmRequirementChannel
```
，其次是
```
HULY_CHANNEL
```
，最后是默认值）。
执行操作前先读取频道历史，然后使用
```
--reply-to-message-id
```
参数对相关队友消息发布明确的帖子内跟进回复。
使用
```
--require-worker-token
```
进行专用账户检查，以拒绝共享的 fallback 令牌。

如需严格的身份映射，请为每个Worker设置

HULY_EXPECTED_ACTOR_ID_<SWARM_AGENT_IDENTITY>

并使用

--require-expected-actor-id

参数。

在自主交付阶段之前运行
```
verify-chat-access
```
，并附带Worker撰写的
```
--message
```
。
在issue/文档产物中包含
```
swarmAgentWorkerId
```
和
```
swarmAgentIdentity
```
字段。
默认保持频道消息人类可读，避免附加元数据块。
- 如果出于特定审计/调试流程需要在聊天中添加元数据，请使用
```
--append-channel-metadata
```
  参数。
- 如果没有显式提供
```
--swarm-agent-worker-id
```
  /
```
--swarm-agent-identity
```
  参数，
```
upsert-mission
```
  会自动从
```
--worker-id/--worker-identity
```
  （或
```
SWARM_AGENT_WORKER_ID
```
  /
```
SWARM_AGENT_IDENTITY
```
  ）中推断这些字段。
保持频道更新简洁，由Worker撰写，并链接到issue/文档/PR/部署凭证。
Issue描述必须是长格式且符合知识库质量要求。辅助工具现在通过协作者引用存储issue描述（而非原始内联markdown），因此看板描述可以可靠渲染和持久化。
```
upsert-mission
```
现在会通过任务id前缀（
```
[mission:<id>]
```
）复用现有任务issue，避免创建重复工单。
使用
```
repair-project-issues
```
迁移仍在
```
Issue.description
```
中使用内联markdown/纯文本的旧版issue。
当历史issue确实存在空描述字段时，使用
```
repair-project-issues --fill-empty-issue-descriptions
```
参数。
使用
```
dedupe-project-mission-issues
```
将较旧的重复任务issue状态改为
```
Canceled
```
，保留最新的活跃issue。
文档内容必须是长格式且符合知识库质量要求。辅助工具现在通过协作者内容引用存储任务文档正文（而非原始内联markdown），因此Huly编辑器/协作者可以一致地加载和渲染内容。
使用
```
repair-teamspace-documents
```
迁移仍在
```
Document.content
```
中使用内联markdown的旧版文档。
如果Huly身份验证失败，请停止运行并返回清晰的解除阻塞请求，不要静默继续。