moda-context

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

moda-context

PREREQUISITE — load
moda-core
once per session (step-0, write contract, free/metered map). Already loaded? Skip ahead. If you cannot load it, the non-negotiables: run

moda doctor --json

before anything;

moda brand list

before creating; every write carries the latest revision — on

stale_revision

, re-read and retry once (it heals); send the canvas link the moment it exists; stuck or failed?

moda ask "<question>"

— free and fast, never guess.

Second run in the same repo landing in the same workspace, on the same kit, against the same canvas? Pin it once and every later run needs no flags.

前提条件——每个会话加载一次
moda-core
（步骤0，签署协议，免费/计量使用说明）。已加载？请跳过。如果无法加载，必须执行：先运行

moda doctor --json

；创建前运行

moda brand list

；每次写入都会携带最新版本——遇到

stale_revision

时，重新读取并重试一次（即可恢复）；画布链接生成后立即发送；遇到问题或失败？运行

moda ask "<question>"

——免费且快速，切勿猜测。

在同一仓库中第二次运行时，是否要进入相同工作区、使用相同工具包、针对相同画布？只需固定一次设置，后续所有运行无需添加参数。

What gets pinned, and where

固定的内容及存储位置

```
.moda/context.json
```
— committed. The repo's shared default, so a teammate's run lands in the same workspace with the same brand.
```
.moda/context.local.json
```
— gitignored. Yours alone; it wins over the committed file.
Three keys only:
```
org
```
,
```
brand
```
,
```
canvas
```
. Discovered by walking up from the working directory, so a subdirectory inherits the repo's pins.

Precedence, highest first: an explicit flag on the command →

MODA_ORG

MODA_API_BASE

in the environment →

context.local.json

→

context.json

→ this install's config → the built-in default.

```
.moda/context.json
```
—— 需提交至仓库。作为仓库的共享默认设置，团队成员的运行也会进入相同工作区并使用相同品牌。
```
.moda/context.local.json
```
—— 需加入git忽略列表。仅个人使用；优先级高于已提交的文件。
仅包含三个键：
```
org
```
、
```
brand
```
、
```
canvas
```
。通过从工作目录向上遍历发现，因此子目录会继承仓库的固定设置。

优先级从高到低：命令中的显式参数 → 环境变量

MODA_ORG

MODA_API_BASE

→

context.local.json

→

context.json

→ 当前安装的配置 → 内置默认值。

The three commands

三个核心命令

moda context show                       # effective values AND where each came from
moda context set brand [bk_…]           # every create in this repo binds this kit
moda context set canvas [cvs_…]         # "the" canvas this repo keeps updating
moda context set org [ORG_ID] --local   # keep a personal org pin out of the commit
moda context clear [key]                # omit the key to clear all three

moda context show

is the first thing to run when a command lands somewhere unexpected: the

[source]

marker on each line names the file or flag that won.

moda context show                       # 显示生效值及每个值的来源
moda context set brand [bk_…]           # 该仓库中的所有创建操作将绑定此工具包
moda context set canvas [cvs_…]         # 该仓库持续更新的“指定”画布
moda context set org [ORG_ID] --local   # 将个人组织固定设置保留在提交之外
moda context clear [key]                # 省略key则清除全部三个设置

当命令运行到意外位置时，首先运行

moda context show

：每行的

[source]

标记会指明生效的文件或参数。

What to pin (and what not to)

固定什么（以及不固定什么）

brand — the kit the repo's work belongs to. Pin it after
```
moda brand list
```
confirms which kit the user means; never guess between two kits.
canvas — only when the repo really has ONE living artifact (the README deck, the status one-pager). A pinned canvas is a default, not a lock: an explicit ref in the ask always wins.
org — whose workspace and billing the work lands in. Never pin or switch an org on your own initiative. Ask, then set exactly what the user names.
Nothing here is secret, so nothing here is a credential: keys live in the OS keychain or the environment, never in these files.

brand —— 仓库工作所属的工具包。在
```
moda brand list
```
确认用户指定的工具包后再固定；切勿在两个工具包之间猜测。
canvas —— 仅当仓库确实只有一个活跃产物时（如README演示文稿、状态单页文档）才固定。固定的画布是默认值，而非锁定：命令中显式指定的引用始终优先。
org —— 工作所属的工作区及计费主体。切勿自行固定或切换组织。先询问用户，再严格按照用户指定的内容设置。
此处无敏感信息，因此不包含凭证：密钥存储在操作系统密钥链或环境变量中，绝不会出现在这些文件里。

Credits and spend

信用额度与消费

moda account status                     # plan + balance — the honest credit check
moda account usage --days 30 [--by-operation]
moda account costs                      # what is metered vs not, from the server

Canvas authoring, reads, screenshots, exports, and sites cost 0 credits on every plan. Only the media-generation and web-research lanes meter.
Direct media calls do not return a per-call credit amount; the balance from
```
moda account status
```
is the honest answer, and totals live in
```
usage
```
.
Answer a "how many credits do we have?" question with the balance and the plan, not an estimate — never hardcode what is metered, read
```
costs
```
.

moda account status                     # 显示套餐+余额——真实的信用额度查询
moda account usage --days 30 [--by-operation]
moda account costs                      # 显示服务器端的计量与非计量项

在所有套餐中，画布创作、读取、截图、导出及站点服务均不消耗信用额度。仅媒体生成和网络研究环节会产生计量费用。
直接媒体调用不会返回单次调用的信用额度消耗；
```
moda account status
```
返回的余额是真实数据，总消耗情况可在
```
usage
```
中查看。
回答“我们还有多少信用额度？”这类问题时，应告知余额和套餐信息，而非估算值——切勿硬编码计量项，需读取
```
costs
```
获取信息。

Examples

示例

"make this repo always use our brand" →
```
moda brand list
```
→ confirm →
```
moda context set brand bk_…
```
→ say what future runs will now do by default.
"why did that land in the wrong workspace?" →
```
moda context show
```
, read the
```
[source]
```
column, fix the file that actually won.
"keep updating the same deck from here" →
```
moda context set canvas cvs_…
```
.
"how much have we spent this month?" →
```
moda account usage --days 30
```
.

“让这个仓库始终使用我们的品牌” → 运行
```
moda brand list
```
→ 确认 → 运行
```
moda context set brand bk_…
```
→ 说明后续运行将默认执行的操作。
“为什么运行到了错误的工作区？” → 运行
```
moda context show
```
，查看
```
[source]
```
列，修改实际生效的文件。
“从此处持续更新同一个演示文稿” → 运行
```
moda context set canvas cvs_…
```
。
“我们本月消费了多少？” → 运行
```
moda account usage --days 30
```
。

Errors

错误处理

Any typed error → load moda-core and read its recovery reference. A pin whose id no longer resolves fails at the verb that uses it, not at

set

— re-run

moda context show

, then re-pin or clear.

任何输入错误 → 加载moda-core并查看其恢复指南。若固定的ID无法解析，会在使用该ID的命令执行时失败，而非

set

命令执行时——重新运行

moda context show

，然后重新固定或清除设置。

Make it recurring

实现自动化运行

A pinned repo is what makes an unattended run flagless — the scheduled half is moda-automate. Pin the brand once and every later artifact is on-brand by default (moda-brand owns the kit itself).

See also: moda-core — the contract, recovery, everything Moda can do.

固定设置后的仓库可实现无参数无人值守运行——调度部分由moda-automate负责。固定品牌后，后续所有产物将默认符合品牌规范（moda-brand负责管理工具包本身）。

另请参阅：moda-core —— 包含协议、恢复指南及Moda的所有功能。