22. Cookbook: рецепты для разработчиков

#[derive(strum::EnumString, strum::IntoStaticStr, ...)]
pub enum SlashCommand {
    // ...
    #[strum(serialize = "foo")]
    Foo,
}

SlashCommand::Foo => match locale {
    TuiLocale::En => "do the foo thing",
    TuiLocale::Ru => "сделать foo",
},

fn supports_inline_args(&self) -> bool {
    matches!(self, Self::Goal | Self::Help | /* ... | */ Self::Foo)
}

fn available_during_task(&self) -> bool { /* добавь в нужный список */ }
fn available_in_side_conversation(&self) -> bool { /* аналогично */ }

.filter(|(_, cmd)| flags.foo_command_enabled || *cmd != SlashCommand::Foo)

pub(crate) foo_command_enabled: bool,

SlashCommand::Foo => {
    self.open_foo_popup();
    QueuedCommandDrainResult::Stop
}

// в overview_lines_en и _ru:
cmd(&mut out, "/foo", "do the foo thing");

// в command_usage:
(SlashCommand::Foo, _) => vec!["/foo"],

// в command_details:
(SlashCommand::Foo, TuiLocale::En) => vec![
    "Detailed explanation, what menu items show up, where state is saved, ...",
],
(SlashCommand::Foo, TuiLocale::Ru) => vec![
    "Подробное описание: какие пункты меню, где сохраняется состояние, ...",
],

cargo test -p astracode-tui slash_commands::tests
cargo insta review   # принять обновлённые snapshots

pub enum ToolHandlerKind {
    // ...
    CountLines,
}

use crate::ResponsesApiTool;
use crate::tool_spec::ToolSpec;

pub(crate) fn create_count_lines_tool() -> ToolSpec {
    // `ToolSpec::Function` — tuple-вариант, оборачивающий `ResponsesApiTool`
    // (см. `tools/src/tool_spec.rs` и `tools/src/responses_api.rs`).
    ToolSpec::Function(ResponsesApiTool {
        name: "count_lines".to_string(),
        description: "Count lines in a file.".to_string(),
        strict: true,
        defer_loading: None,
        parameters: JsonSchema::object(
            BTreeMap::from([(
                "path".to_string(),
                JsonSchema::string(Some("Path to the file.".to_string())),
            )]),
            Some(vec!["path".to_string()]),
            Some(false.into()),
        ),
        output_schema: None,
    })
}

plan.add(create_count_lines_tool(), ToolHandlerKind::CountLines);

pub(crate) async fn execute_count_lines(
    args: CountLinesArgs,
    ctx: &TurnContext,
) -> Result<String> {
    let path = ctx.resolve_path(&args.path)?;
    let content = ctx.file_system.read_to_string(&path).await?;
    Ok(format!("{}", content.lines().count()))
}

ToolHandlerKind::CountLines => execute_count_lines(parse_args(args)?, ctx).await,

#[test]
fn count_lines_spec_has_required_path_param() {
    let spec = create_count_lines_tool();
    // assert that JSON-schema has required: ["path"]
}

#[derive(Serialize, Deserialize, JsonSchema, TS)]
pub struct ThreadFooBarParams {
    pub thread_id: ThreadId,
    pub value: bool,
}

#[derive(Serialize, Deserialize, JsonSchema, TS)]
pub struct ThreadFooBarResponse {
    pub previous_value: bool,
}

client_request_definitions! {
    // ...
    "thread/foo/bar" => ThreadFooBarParams => ThreadFooBarResponse,
}

ClientRequest::ThreadFooBar(params) => {
    let response = self.thread_foo_bar(params).await?;
    Ok(JSONRPCResponse { id, result: serde_json::to_value(response)? })
}

impl AstraCode {
    pub async fn set_foo(&self, value: bool) -> Result<bool> {
        let mut state = self.session.state.lock().await;
        let previous = state.foo;
        state.foo = value;
        Ok(previous)
    }
}

"thread/foo/updated" => ThreadFooUpdatedNotification,

session.send_notification(ServerNotification::ThreadFooUpdated(...)).await;

self.client.thread_foo_bar(ThreadFooBarParams { thread_id, value: true }).await?;

pub enum HookEvent {
    // ...
    BeforeCompact,
}

#[serde(rename = "BeforeCompact")]
BeforeCompact(Vec<HookHandler>),

self.hook_engine.fire(HookEvent::BeforeCompact, HookContext::new(...)).await?;

context.set("history_size", state.message_history.len());

// Было:
let msg = "Something happened.".to_string();

// Стало:
let msg = match locale {
    TuiLocale::En => "Something happened.".to_string(),
    TuiLocale::Ru => "Что-то произошло.".to_string(),
};

let locale = session.tui_locale().await;
let msg = match locale { /* ... */ };

cargo test -p astracode-tui
cargo insta review

pub struct Config {
    // ...
    pub feature_foo_enabled: bool,
}

feature_foo_enabled: cfg.features.as_ref()
    .map(|f| f.foo.unwrap_or(false))
    .unwrap_or(false),

cargo build --workspace  # покажет где забыли инициализировать

if config.feature_foo_enabled { /* ... */ }

#[test]
fn my_function_renders_correctly() {
    let output = my_function(SomeInput {});
    insta::assert_snapshot!(output);
}

insta::assert_debug_snapshot!(my_struct);
insta::assert_json_snapshot!(my_struct);

cargo test -p astracode-tui my_function_renders_correctly

cargo insta review
# 'a' — принять, 's' — пропустить, 'r' — отклонить

[[providers]]
id = "company-llm"
display_name = "Company LLM Gateway"
base_url = "https://llm.company.internal/v1"

default_provider = "company-llm"
model = "llama-3.3-70b"

export ASTRACODE_CA_CERTIFICATE=/etc/ssl/certs/company-ca.pem
astracode

astracode -c model_provider=company-llm
# В TUI:
/status

[mcp_servers.my_python_server]
command = "python"
args = ["-m", "my_mcp_module"]
env_vars = ["MY_API_KEY"]
default_tools_approval_mode = "prompt"
startup_timeout_sec = 30

$skill-creator

mkdir -p ~/.astracode/skills/my-skill/agents
cat > ~/.astracode/skills/my-skill/SKILL.md << 'EOF'
---
name: my-skill
description: "Concise description of what this skill does and when to use it."
metadata:
  short-description: "Brief one-liner (EN)"
  short-description-ru: "Краткое описание (RU)"
---

# my-skill

Detailed instructions for the agent...
EOF

RUST_LOG=astracode_core=debug,astracode_tui=info astracode 2> /tmp/astracode.log

/rollout

ls -t ~/.astracode/sessions/$(date +%Y/%m/%d)/ | head -1

/debug-config

sqlite3 ~/.astracode/state_5.sqlite "SELECT id, title, model_provider, updated_at FROM threads ORDER BY updated_at DESC LIMIT 10;"

/status

# Бэкап секретов и кастомных скиллов
tar czf astracode-backup.tar.gz \
  ~/.astracode/secrets/ \
  ~/.astracode/config.toml \
  $(ls -d ~/.astracode/skills/*/ 2>/dev/null | grep -v .system)

# Снести всё (ОПАСНО — секреты и сессии потеряются если бэкап не сделан)
rm -rf ~/.astracode

# Запустить заново — конфиг сгенерируется
astracode

# В Cargo.toml workspace добавить sccache
# В ~/.cargo/config.toml:
[build]
rustc-wrapper = "sccache"
incremental = true

[target.x86_64-unknown-linux-gnu]
linker = "clang"
rustflags = ["-C", "link-arg=-fuse-ld=mold"]

cargo install sccache
sudo apt install mold clang

# Включить debug-symbols в release-builds (временно)
RUSTFLAGS="-g" cargo build --release --bin astracode

# Perf record
perf record --call-graph dwarf ./target/release/astracode
perf report

# Flamegraph
cargo install flamegraph
cargo flamegraph --bin astracode --release

// В main.rs добавить:
#[cfg(feature = "tokio-console")]
console_subscriber::init();

cargo build --features tokio-console
tokio-console

use core_test_support::responses::ev_assistant_message;
use core_test_support::responses::ev_completed;
use core_test_support::responses::ev_response_created;
use core_test_support::responses::mount_sse_once;
use core_test_support::responses::sse;
use core_test_support::responses::start_mock_server;
use core_test_support::skip_if_no_network;
use core_test_support::test_astracode::test_astracode;

#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
async fn my_e2e_test() -> anyhow::Result<()> {
    skip_if_no_network!(Ok(()));

    // 1. Поднять мок-сервер Responses API.
    let server = start_mock_server().await;

    // 2. Смонтировать один SSE-ответ модели.
    let response_mock = mount_sse_once(
        &server,
        sse(vec![
            ev_response_created("resp-1"),
            ev_assistant_message("msg-1", "Hello, world!"),
            ev_completed("resp-1"),
        ]),
    )
    .await;

    // 3. Собрать тестовый AstraCode, указывающий на мок-сервер.
    let test = test_astracode().build(&server).await?;
    test.submit_turn_with_environments("Say hello", None).await?;

    // 4. Проверить, что именно ушло в модель.
    let request = response_mock.single_request();
    assert!(request.body_contains_text("Say hello"));

    Ok(())
}

# 1. Обновить версии (пример: текущая 0.4.11 → новая 0.4.11)
sed -i 's/version = "0.4.11"/version = "0.4.11"/' astracode-rs/Cargo.toml
sed -i 's/"version": "0.4.11"/"version": "0.4.11"/' astracode-cli/package.json

# 2. Обновить snapshot-тесты
find astracode-rs/tui/src/status/snapshots -name '*.snap' \
  | xargs sed -i 's/AstraCode (v0.4.11)/AstraCode (v0.4.12)/g'

# 3. Сгенерировать CHANGELOG
git-cliff --tag 0.4.11 > CHANGELOG.md

# 4. Прогнать тесты
cd astracode-rs && cargo test --workspace
cargo insta review

# 5. Commit + tag + push
git add -A
git commit -m "chore(release): bump to 0.4.11"
git tag 0.4.11
git push origin main 0.4.11