project-manager

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Project Manager

项目管理器

Manage projects, grants, milestones, and updates on the Karma protocol. All actions create on-chain attestations via a single API.

Full API docs:

https://gapapi.karmahq.xyz/v2/docs/static/index.html

bash

BASE_URL="${KARMA_API_URL:-https://gapapi.karmahq.xyz}"
API_KEY="${KARMA_API_KEY}"
INVOCATION_ID=$(uuidgen)

CRITICAL: Every
curl
call must include these tracking headers:

bash

-H "X-Source: skill:project-manager"
-H "X-Invocation-Id: $INVOCATION_ID"
-H "X-Skill-Version: 1.0.0"

在Karma协议上管理项目、资助、里程碑和更新内容。所有操作都通过单一API创建链上证明。

完整API文档：

https://gapapi.karmahq.xyz/v2/docs/static/index.html

bash

BASE_URL="${KARMA_API_URL:-https://gapapi.karmahq.xyz}"
API_KEY="${KARMA_API_KEY}"
INVOCATION_ID=$(uuidgen)

重要提示：每个
curl
调用必须包含以下追踪头信息：

bash

-H "X-Source: skill:project-manager"
-H "X-Invocation-Id: $INVOCATION_ID"
-H "X-Skill-Version: 1.0.0"

Setup

设置流程

KARMA_API_KEY

is already set, skip to Verify.

Otherwise use the

AskUserQuestion

tool with these options:

Question: "You need a Karma API key to continue. How would you like to set it up?"
Options: ["Quick start — Generate instantly (no account needed)", "Email login — Link to existing Karma account", "I already have a key"]

如果已设置

KARMA_API_KEY

，请跳至验证。

否则使用

AskUserQuestion

工具并提供以下选项：

问题："您需要Karma API密钥才能继续。您希望如何设置？"
选项：["快速开始——立即生成（无需账户）", "邮箱登录——关联现有Karma账户", "我已有密钥"]

Quick Start (No Account Needed)

快速开始（无需账户）

bash

curl -s -X POST "${BASE_URL}/v2/agent/register" \
  -H "Content-Type: application/json" \
  -H "X-Source: skill:project-manager" -H "X-Invocation-Id: $INVOCATION_ID" -H "X-Skill-Version: 1.0.0" \
  -d '{}'

Returns

{ "apiKey": "karma_..." }

— shown only once.

Important: Always send

-d '{}'

— an empty body causes a 400 error.

bash

curl -s -X POST "${BASE_URL}/v2/agent/register" \
  -H "Content-Type: application/json" \
  -H "X-Source: skill:project-manager" -H "X-Invocation-Id: $INVOCATION_ID" -H "X-Skill-Version: 1.0.0" \
  -d '{}'

返回结果为

{ "apiKey": "karma_..." }

——该密钥仅显示一次。

注意：必须始终发送
-d '{}'
——空请求体将导致400错误。

Email Login

邮箱登录

Ask for email

POST ${BASE_URL}/v2/api-keys/auth/init

with

{ "email": "..." }

Ask for code →

POST ${BASE_URL}/v2/api-keys/auth/verify

with

{ "email": "...", "code": "...", "name": "claude-agent" }

Returns
```
{ "key": "karma_..." }
```

Error	Action
`400 Invalid or expired code`	Ask to recheck or request new code
`409 Active key already exists`	Use existing key or revoke from website

请求用户提供邮箱

向

POST ${BASE_URL}/v2/api-keys/auth/init

发送

{ "email": "..." }

请求用户提供验证码 → 向

POST ${BASE_URL}/v2/api-keys/auth/verify

发送

{ "email": "...", "code": "...", "name": "claude-agent" }

返回结果为
```
{ "key": "karma_..." }
```

错误信息	处理操作
`400 Invalid or expired code`	提示用户检查验证码或请求新验证码
`409 Active key already exists`	提示用户使用现有密钥或从网站撤销旧密钥

Save API Key

保存API密钥

After obtaining the key (from quick start, email login, or user pasting it), ask permission to save it permanently:

Would you like me to save your API key to your shell config so you don't have to paste it every time?

If yes, detect the user's shell and append the export:

bash

undefined

获取密钥后（通过快速开始、邮箱登录或用户粘贴），请先征得用户许可再永久保存：

是否希望我将您的API密钥保存到shell配置文件中，这样您就无需每次都粘贴密钥？

如果用户同意，检测用户的shell并追加导出命令：

bash

undefined

Detect shell config file

检测shell配置文件

if [ -f "$HOME/.zshrc" ]; then SHELL_RC="$HOME/.zshrc" elif [ -f "$HOME/.bashrc" ]; then SHELL_RC="$HOME/.bashrc" fi

Append only if not already present

仅当密钥未存在时追加

grep -q 'KARMA_API_KEY' "$SHELL_RC" || echo '\n# Karma API Key\nexport KARMA_API_KEY="karma_..."' >> "$SHELL_RC"

Also export for current session

同时在当前会话中导出

export KARMA_API_KEY="karma_..."


If the key already exists in the file, replace the old value instead of appending a duplicate.

If the user declines, just set it for the current session:

```bash
export KARMA_API_KEY="karma_..."

export KARMA_API_KEY="karma_..."


如果配置文件中已存在密钥，请替换旧值而非追加重复项。

如果用户拒绝，仅在当前会话中设置密钥：

```bash
export KARMA_API_KEY="karma_..."

Verify

验证

bash

curl -s "${BASE_URL}/v2/agent/info" \
  -H "x-api-key: ${API_KEY}" \
  -H "X-Source: skill:project-manager" -H "X-Invocation-Id: $INVOCATION_ID" -H "X-Skill-Version: 1.0.0"

If response includes

walletAddress

and

supportedActions

→ ready. Do NOT show wallet/chain details to the user. Tell them:

Your Karma agent is ready! You can now create projects, grants, milestones, and post updates.

bash

curl -s "${BASE_URL}/v2/agent/info" \
  -H "x-api-key: ${API_KEY}" \
  -H "X-Source: skill:project-manager" -H "X-Invocation-Id: $INVOCATION_ID" -H "X-Skill-Version: 1.0.0"

如果响应包含

walletAddress

和

supportedActions

→ 配置完成。请勿向用户显示钱包或链的详细信息，只需告知：

您的Karma Agent已准备就绪！现在您可以创建项目、添加资助、设置里程碑并发布更新。

Execute Endpoint

执行端点

All actions use:

bash

curl -s -X POST "${BASE_URL}/v2/agent/execute" \
  -H "Content-Type: application/json" \
  -H "x-api-key: ${API_KEY}" \
  -H "X-Source: skill:project-manager" -H "X-Invocation-Id: $INVOCATION_ID" -H "X-Skill-Version: 1.0.0" \
  -d '{ "action": "<ACTION>", "params": { ... } }'

所有操作均使用以下模板：

bash

curl -s -X POST "${BASE_URL}/v2/agent/execute" \
  -H "Content-Type: application/json" \
  -H "x-api-key: ${API_KEY}" \
  -H "X-Source: skill:project-manager" -H "X-Invocation-Id: $INVOCATION_ID" -H "X-Skill-Version: 1.0.0" \
  -d '{ "action": "<ACTION>", "params": { ... } }'

Success Output

成功输出

[Action] completed successfully!

- Project: {title}
- Chain: {chainName} ({chainId})
- Transaction: {transactionHash}

[操作]已成功完成！

- 项目：{title}
- 区块链：{chainName} ({chainId})
- 交易：{transactionHash}

Supported Chains

支持的区块链

Chain	ID
Arbitrum	42161
Base	8453
Celo	42220
Lisk	1135
Optimism	10
Polygon	137
Scroll	534352
Sei	1329
Testnets
Base Sepolia	84532
OP Sepolia	11155420

区块链	ID
Arbitrum	42161
Base	8453
Celo	42220
Lisk	1135
Optimism	10
Polygon	137
Scroll	534352
Sei	1329
测试网
Base Sepolia	84532
OP Sepolia	11155420

Default Chain Behavior

默认区块链行为

When the user does NOT specify a chain, default to Base (8453) and confirm:

Your project will be created on Base. Continue?

Yes

Choose another chain: Arbitrum, Base, Celo, Lisk, Optimism, Polygon, Scroll, Sei

当用户未指定区块链时，默认使用**Base (8453)**并向用户确认：

您的项目将创建在Base链上。是否继续？

是

选择其他链：Arbitrum、Base、Celo、Lisk、Optimism、Polygon、Scroll、Sei

Chain Inheritance

区块链继承规则

Child attestations must use the same chain as their parent:

Grant → uses
```
project.chainId
```
Grant Update → uses
```
grant.chainId
```
Milestone → uses
```
grant.chainId
```
Complete Milestone → uses
```
milestone.chainId
```
Project Update → uses
```
project.chainId
```

Look up the parent's chain from the API — never ask the user for a chain on child attestations.

子证明必须使用与父项相同的区块链：

资助 → 使用
```
project.chainId
```
资助更新 → 使用
```
grant.chainId
```
里程碑 → 使用
```
grant.chainId
```
完成里程碑 → 使用
```
milestone.chainId
```
项目更新 → 使用
```
project.chainId
```

从API中查询父项的区块链信息——绝不要在子证明操作时询问用户区块链。

Actions

操作列表

createProject

Param	Required	Description
`chainId`	Yes	Blockchain ID (default: Base 8453)
`title`	Yes	Project name (1-200 chars)
`description`	Yes	Project description (1-5000 chars)

Optional fields:

Param	Description
`imageURL`	Logo/image URL
`links`	Array of `{ type, url }` — github, website, twitter, discord
`tags`	Array of strings (max 20) — e.g. "defi", "infrastructure"
`problem`	What problem does this project solve? (1-5000 chars)
`solution`	What is the solution? (1-5000 chars)
`missionSummary`	Brief mission statement (1-1000 chars)
`locationOfImpact`	Geographic or domain focus (1-1000 chars)
`businessModel`	How does the project sustain itself? (1-1000 chars)
`stageIn`	Development stage: Idea, MVP, Beta, Production, Growth, Mature (1-1000 chars)
`raisedMoney`	Funding raised so far (1-1000 chars)
`pathToTake`	Future roadmap (1-1000 chars)

参数	是否必填	描述
`chainId`	是	区块链ID（默认：Base 8453）
`title`	是	项目名称（1-200字符）
`description`	是	项目描述（1-5000字符）

可选字段：

参数	描述
`imageURL`	项目Logo/图片URL
`links`	`{ type, url }` 数组——支持github、website、twitter、discord
`tags`	字符串数组（最多20个）——例如"defi"、"infrastructure"
`problem`	项目解决的问题（1-5000字符）
`solution`	项目的解决方案（1-5000字符）
`missionSummary`	简短的使命宣言（1-1000字符）
`locationOfImpact`	影响范围（地理或领域，1-1000字符）
`businessModel`	项目的可持续运营模式（1-1000字符）
`stageIn`	开发阶段：Idea、MVP、Beta、Production、Growth、Mature（1-1000字符）
`raisedMoney`	已筹集资金（1-1000字符）
`pathToTake`	未来路线图（1-1000字符）

Gathering Project Information

收集项目信息

When the user wants to create a project, present all fields at once and let them fill in what they want:

To create your project, provide the following. Only title and description are required — the rest helps your project stand out:

Title: Project name

Description: What does the project do?

Problem: What problem are you solving?

Solution: How does your project solve it?

Mission: Sum up your mission in one sentence

Stage: Idea / MVP / Beta / Production / Growth / Mature

Location of Impact: Where or who does it impact?

Business Model: How do you sustain the project?

Funding Raised: What funding have you received?

Roadmap: What's your plan ahead?

Links: GitHub, website, Twitter, Discord URLs

Tags: Category tags (e.g. defi, infrastructure, public-goods)

Image: Logo or banner URL

Include only the fields the user provides — all metadata fields are optional.

当用户想要创建项目时，一次性展示所有字段并让用户填写所需内容：

要创建您的项目，请提供以下信息。仅标题和描述为必填项——其余信息有助于您的项目脱颖而出：

标题：项目名称

描述：项目的功能是什么？

问题：您正在解决什么问题？

解决方案：您的项目如何解决该问题？

使命：用一句话总结您的使命

阶段：Idea / MVP / Beta / Production / Growth / Mature

影响范围：影响的地域或人群？

商业模式：您如何维持项目运营？

已筹资金：您已获得哪些资助？

路线图：您未来的计划是什么？

链接：GitHub、官网、Twitter、Discord的URL

标签：分类标签（例如defi、infrastructure、public-goods）

图片：Logo或横幅URL

仅包含用户提供的字段——所有元数据字段均为可选。

After Project Creation

项目创建完成后

After a successful project creation, display:

Your project has been created on {chainName}!

Project: {title}

Chain: {chainName} ({chainId})

Transaction: {transactionHash}

Want to post your first update? Share something you just built, a milestone you hit, or what's coming next.

项目创建成功后，显示以下内容：

您的项目已在{chainName}链上创建完成！

项目：{title}

区块链：{chainName} ({chainId})

交易：{transactionHash}

想要发布您的第一条更新吗？分享您刚完成的工作、达成的里程碑或未来计划。

updateProjectDetails

Update an existing project. Replaces all fields — fetch current details first for partial updates.

Param	Required	Description
`chainId`	Yes	Chain where the project lives
`projectUID`	Yes	Project attestation UID
`title`	Yes	Project name (1-200 chars)
`description`	Yes	Project description (1-5000 chars)

Plus all optional fields from

createProject

(imageURL, links, tags, problem, solution, missionSummary, locationOfImpact, businessModel, stageIn, raisedMoney, pathToTake).

Important: Always include existing fields alongside changes since the update replaces everything.

更新现有项目。将替换所有字段——如需部分更新，请先获取当前详细信息。

参数	是否必填	描述
`chainId`	是	项目所在的区块链
`projectUID`	是	项目证明UID
`title`	是	项目名称（1-200字符）
`description`	是	项目描述（1-5000字符）

以及

createProject

中的所有可选字段（imageURL、links、tags、problem、solution、missionSummary、locationOfImpact、businessModel、stageIn、raisedMoney、pathToTake）。

重要提示：更新时必须包含现有字段和更改内容，因为更新操作会替换所有信息。

createProjectUpdate

Post a progress update on a project.

Param	Required	Description
`chainId`	Yes	Must match project's chain
`projectUID`	Yes	Project attestation UID
`title`	Yes	Update title (1-200 chars)
`text`	Yes	Update content (1-10000 chars)

发布项目进度更新。

参数	是否必填	描述
`chainId`	是	必须与项目所在区块链一致
`projectUID`	是	项目证明UID
`title`	是	更新标题（1-200字符）
`text`	是	更新内容（1-10000字符）

createGrant

Add a grant (funding) to a project.

Param	Required	Description
`chainId`	Yes	Must match project's chain
`projectUID`	Yes	Project attestation UID
`communityUID`	Yes	Community attestation UID
`title`	Yes	Grant title (1-200 chars)
`description`	No	Grant description (1-5000 chars)
`amount`	No	Funding amount (e.g. "50000 USDC")
`proposalURL`	No	Link to grant proposal
`programId`	No	Program ID (look up via programs API)

为项目添加资助（资金）。

参数	是否必填	描述
`chainId`	是	必须与项目所在区块链一致
`projectUID`	是	项目证明UID
`communityUID`	是	社区证明UID
`title`	是	资助标题（1-200字符）
`description`	否	资助描述（1-5000字符）
`amount`	否	资助金额（例如"50000 USDC"）
`proposalURL`	否	资助提案链接
`programId`	否	项目ID（通过programs API查询）

createGrantUpdate

Post a progress update on a grant.

Param	Required	Description
`chainId`	Yes	Must match grant's chain
`grantUID`	Yes	Grant attestation UID
`title`	Yes	Update title (1-200 chars)
`text`	Yes	Update content (1-10000 chars)

发布资助进度更新。

参数	是否必填	描述
`chainId`	是	必须与资助所在区块链一致
`grantUID`	是	资助证明UID
`title`	是	更新标题（1-200字符）
`text`	是	更新内容（1-10000字符）

createMilestone

Add a milestone to a grant.

Param	Required	Description
`chainId`	Yes	Must match grant's chain
`grantUID`	Yes	Grant attestation UID
`title`	Yes	Milestone title (1-200 chars)
`description`	Yes	What will be delivered (1-5000 chars)
`endsAt`	Yes	Deadline as Unix timestamp in seconds
`priority`	No	Priority level (0-4)

Date conversion:

Math.floor(new Date("2025-06-30").getTime() / 1000)

为资助添加里程碑。

参数	是否必填	描述
`chainId`	是	必须与资助所在区块链一致
`grantUID`	是	资助证明UID
`title`	是	里程碑标题（1-200字符）
`description`	是	交付内容描述（1-5000字符）
`endsAt`	是	截止时间（Unix时间戳，单位为秒）
`priority`	否	优先级（0-4）

日期转换示例：

Math.floor(new Date("2025-06-30").getTime() / 1000)

completeMilestone

Mark a milestone as completed.

Param	Required	Description
`chainId`	Yes	Must match milestone's chain
`milestoneUID`	Yes	Milestone attestation UID
`reason`	Yes	Completion summary (1-5000 chars)
`proofOfWork`	No	URL to proof (PR, demo, report)

将里程碑标记为已完成。

参数	是否必填	描述
`chainId`	是	必须与里程碑所在区块链一致
`milestoneUID`	是	里程碑证明UID
`reason`	是	完成总结（1-5000字符）
`proofOfWork`	否	工作成果证明链接（PR、演示报告）

createProjectWithGrant

Create a project and grant in a single transaction (4 attestations).

All

createProject

params plus:

Param	Required	Description
`communityUID`	Yes	Community attestation UID
`grant.title`	Yes	Grant title (1-200 chars)
`grant.description`	No	Grant description
`grant.amount`	No	Funding amount
`grant.proposalURL`	No	Proposal link
`grant.programId`	No	Program ID

After success, use the same post-creation message as

createProject

在单次交易中创建项目和资助（生成4个证明）。

包含

createProject

的所有参数，以及：

参数	是否必填	描述
`communityUID`	是	社区证明UID
`grant.title`	是	资助标题（1-200字符）
`grant.description`	否	资助描述
`grant.amount`	否	资助金额
`grant.proposalURL`	否	提案链接
`grant.programId`	否	项目ID

成功后，使用与

createProject

相同的创建完成提示信息。

Looking Up Data

数据查询

Find a Project

查找项目

bash

curl -s -H "X-Source: skill:project-manager" -H "X-Invocation-Id: $INVOCATION_ID" -H "X-Skill-Version: 1.0.0" \
  "${BASE_URL}/v2/projects?q=SEARCH_TERM&limit=5&page=1"

Each result has:

uid

chainID

details.title

details.slug

details.description

bash

curl -s -H "X-Source: skill:project-manager" -H "X-Invocation-Id: $INVOCATION_ID" -H "X-Skill-Version: 1.0.0" \
  "${BASE_URL}/v2/projects?q=SEARCH_TERM&limit=5&page=1"

每个结果包含：

uid

、

chainID

、

details.title

、

details.slug

、

details.description

Get Project by UID or Slug

通过UID或Slug获取项目

bash

curl -s -H "X-Source: skill:project-manager" -H "X-Invocation-Id: $INVOCATION_ID" -H "X-Skill-Version: 1.0.0" \
  "${BASE_URL}/v2/projects/PROJECT_UID_OR_SLUG"

bash

curl -s -H "X-Source: skill:project-manager" -H "X-Invocation-Id: $INVOCATION_ID" -H "X-Skill-Version: 1.0.0" \
  "${BASE_URL}/v2/projects/PROJECT_UID_OR_SLUG"

Get Project Grants

获取项目的资助信息

bash

curl -s -H "X-Source: skill:project-manager" -H "X-Invocation-Id: $INVOCATION_ID" -H "X-Skill-Version: 1.0.0" \
  "${BASE_URL}/v2/projects/PROJECT_UID_OR_SLUG/grants"

Each grant has:

uid

details.title

milestones[]

bash

curl -s -H "X-Source: skill:project-manager" -H "X-Invocation-Id: $INVOCATION_ID" -H "X-Skill-Version: 1.0.0" \
  "${BASE_URL}/v2/projects/PROJECT_UID_OR_SLUG/grants"

每个资助包含：

uid

、

details.title

、

milestones[]

Search Communities

搜索社区

bash

curl -s -H "X-Source: skill:project-manager" -H "X-Invocation-Id: $INVOCATION_ID" -H "X-Skill-Version: 1.0.0" \
  "${BASE_URL}/v2/communities/?limit=5&page=1"

bash

curl -s -H "X-Source: skill:project-manager" -H "X-Invocation-Id: $INVOCATION_ID" -H "X-Skill-Version: 1.0.0" \
  "${BASE_URL}/v2/communities/?limit=5&page=1"

Get Community Programs

获取社区项目

bash

curl -s -H "X-Source: skill:project-manager" -H "X-Invocation-Id: $INVOCATION_ID" -H "X-Skill-Version: 1.0.0" \
  "${BASE_URL}/communities/COMMUNITY_SLUG_OR_UID/programs"

Each program has:

programId

metadata.title

. Always include

programId

when the user mentions a specific program.

bash

curl -s -H "X-Source: skill:project-manager" -H "X-Invocation-Id: $INVOCATION_ID" -H "X-Skill-Version: 1.0.0" \
  "${BASE_URL}/communities/COMMUNITY_SLUG_OR_UID/programs"

每个项目包含：

programId

、

metadata.title

。当用户提及特定项目时，必须包含

programId

。

Natural Language Mapping

自然语言映射

User says	Action
"create a project", "new project"	`createProject` — present all fields, default Base
"create a DeFi project on Optimism"	`createProject` with tags: ["defi"], chainId: 10
"update project details", "rename project", "enrich my project"	`updateProjectDetails` — fetch current details first
"post an update", "project progress"	`createProjectUpdate` — look up projectUID, inherit chain
"add a grant", "record funding"	`createGrant` — look up projectUID + communityUID, inherit chain
"grant update", "grant progress"	`createGrantUpdate` — look up grantUID, inherit chain
"add milestone", "set deliverable"	`createMilestone` — look up grantUID, inherit chain
"complete milestone", "mark done"	`completeMilestone` — look up milestoneUID, inherit chain
"create project with grant"	`createProjectWithGrant`

用户表述	对应操作
"create a project", "new project"	`createProject` — 展示所有字段，默认使用Base链
"create a DeFi project on Optimism"	`createProject` ，标签为["defi"]，chainId为10
"update project details", "rename project", "enrich my project"	`updateProjectDetails` — 先获取当前详细信息
"post an update", "project progress"	`createProjectUpdate` — 查询projectUID，继承区块链
"add a grant", "record funding"	`createGrant` — 查询projectUID和communityUID，继承区块链
"grant update", "grant progress"	`createGrantUpdate` — 查询grantUID，继承区块链
"add milestone", "set deliverable"	`createMilestone` — 查询grantUID，继承区块链
"complete milestone", "mark done"	`completeMilestone` — 查询milestoneUID，继承区块链
"create project with grant"	`createProjectWithGrant`

Error Handling

错误处理

Status	Meaning	Action
400	Bad params	Show error, help fix
401	Invalid API key	Tell user to check `KARMA_API_KEY` or run setup
429	Rate limited (60/min)	Wait and retry
500	Server error	Retry once, then report

状态码	含义	处理操作
400	参数错误	显示错误信息，帮助用户修复
401	API密钥无效	告知用户检查 `KARMA_API_KEY` 或重新运行设置流程
429	请求频率超限（每分钟60次）	等待后重试
500	服务器错误	重试一次，若仍失败则报告问题

Edge Cases

边缘情况处理

Scenario	Response
Missing required field	Ask user for it
Chain not specified (root action)	Default to Base, confirm with user
Chain not specified (child action)	Inherit from parent — never ask
API key not set	Run setup flow
Title too long (>200)	Truncate and confirm
Need UID but user gave name	Search API to find the UID
Partial project update	Fetch current details, merge changes, then update
Multiple grants on project	Show list, ask which one
Date given as string	Convert to Unix timestamp in seconds

场景	响应方式
缺少必填字段	请求用户提供该字段
未指定区块链（根操作）	默认使用Base链，向用户确认
未指定区块链（子操作）	继承父项的区块链——绝不询问用户
未设置API密钥	运行设置流程
标题过长（超过200字符）	截断后向用户确认
需要UID但用户提供了名称	通过API搜索获取UID
部分项目更新	获取当前详细信息，合并更改后再更新
项目有多个资助	展示列表，询问用户选择哪个
用户提供字符串格式的日期	转换为Unix时间戳（单位为秒）